javascript-style-guide
javascript-style-guide copied to clipboard
pagarme
Remover "Unexpected mix of '*' and '+'." e "Infix operators must be spaced."
Fora a obviedade, escrever
(a * x) + b
Tira a clareza frente à:
a*x + b
É extremamente comum até mesmo omitir o operador multiplicativo, quando se escreve algo do tipo: https://en.wikipedia.org/wiki/Linear_equation#Two_variables
Não a toa facilita o entendimento e leitura remover essas regras e permitir que o espaçamento seja semântico, bem como a precedência de operadores.
Tirar o "Unexpected mix of '*' and '+'." é justo apesar de que ele cobre casos que ficariam bem feios. (a * x) + b é simples mas 5 * 9 + 1 / 5 - 2 + 7 * 3 fica bem feio por exemplo.
Agora sobre o "Infix operators must be spaced." eu discordo. Tirar essa regra abre muito espaço pra coisa inconsistente tipo a *x +b e não devemos confiar que no review pegamos essas coisas se temos um linter pra isso
Aí q tá @MarcoWorms, eu discordo de argumentos de "o linter não vai pegar isso", essa é a minha birra com linters em geral: eu não acredito que seja possível existir um linter "completo".
Eu gosto de code style, eu detesto linter muito estrito, pq ele perde exatamente o propósito dele, que é ter código de qualidade, na minha opinião, ele tem q cobrir oq ele consegue cobrir, oq ele não consegue, ele não deveria nem tentar.
Eu não acredito que um linter vai deixar um código melhor, ele pode ajudar, bem como ele pode atrapalhar quando por falta de capacidade de analisar semanticamente caga legibilidade.
Concordo que a *x +b é zuado, e deve ser tão evitado qto a * x + b.
Um outro exemplo mais bizarro de como as coisas ficam feias como estão é uma tosqueira de um polinômio de segundo grau:
((a - a0) * (x ** 2)) + ((b - b0) * x) + c
vs
(a - a0) * (x ** 2) + (b - b0) * x + c
vs
(a-a0)*(x**2) + (b-b0)*x + c
A proximidade ajuda muito na leitura, não a toa designers pensam em espaço quando tratam sobre diagramação, não a toa papers científicos escrevem expressões de preferencialmente mais parecidos com a terceira forma.
(a - a0) * (x ** 2) + (b - b0) * x + c
é mais legível que
(a-a0)*(x**2) + (b-b0)*x + c
Olha, o principal propósito de uma regra como "Infix operators must be spaced" é que ela garante consistência de equações matemáticas.
O que impediria alguém de escrever
(a-a0)*(x**2)+(b-b0)*x+c ?
Além disso, se você está achando a informação muito densa, talvez não esteja nomeando as partes da equação com nomes expressivos.
Compare:
delta_a = a - a0
delta_b = b - b0
return delta_a * x ** 2 + delta_b * x + c
O que impediria alguém de escrever
Resposta dada anteriormente
Eu não acredito que um linter vai deixar um código melhor, ele pode ajudar, bem como ele pode atrapalhar quando por falta de capacidade de analisar semanticamente caga legibilidade.
Quando falo em legibilidade, ao invés de apenas jogar um feeling estético meu, uso as mesmas idéias de quando penso em design e diagramação de conteúdo, pq quer queira, quer não, nesse mundo o pessoal se preocupa muito mais com isso doq em código.
DISCLAIMER: Daqui em diante isso vai virar um ranting meu. Me dói usar um code style ILEGIVEL como o que usamos, portanto vou explicar bem didaticamente pq eu detesto ele ponto a ponto, pela última vez, aí se as pessoas discordarem, me considero vencido e não questiono mais nada quanto a isso, pq to me cansado e frustrado PR a PR quando tento fazer algo que julgo bom.
Qdo falamos em legibilidade não adianta cada um vir com a sua "arte" ou oq acha mais bonito. Nessas horas eu me reduzo a pensar nos 4 princípios básicos de design:
- Proximidade
- Alinhamento
- Paralelismo/Repetição
- Contraste
Um livro bacana pra ler sobre isso é esse: https://www.amazon.com/exec/obidos/ASIN/0321193857/codihorr-20
Aí a coisa desanda... E com essa cabeça q eu tenho, tlvz seja melhor virar designer a continuar a codar em js aqui, pq agente usa um style guide que quase sempre vai contra esses princípios
Proximidade
Trata de aproximar coisas de contexto semelhante e distanciar coisas distintas. Eu gosto de escrever meu código quebrando com linhas em branco contextos que julgo semânticos, isso é algo que nunca nenhum linter vai fazer, pq carrega significado semântico, só qdo tivermos uma AGI tlvz consigamos isso.
Qdo notamos como o latex diagrama o resultado de expressões matemáticas, ele já se preocupa em fazer isso de uma maneira razoável com espaçamentos, coisa que complica qdo tratamos de código... Oq é uma equação? Oq é um código? Só por ser código vamos sair criando variáveis a esmo pra deixar mais "legível"? Um termo matemático não faz sentido de estar agrupado com espaço qdo ele carrega um significado semântico?
Qdo vejo isso:
(a-a0)*(x**2) + (b-b0)*x + c ou delta_a*(x**2) + delta_b*x + c
O que me faz decidir oq faz mais sentido é o contexto semântico, por exemplo, se a e a0 são constantes, tlvz eu tenda a gostar de agrupar num delta_a, mas se a for um input, portanto eu for pensar nisso como uma variável matemática, eu julgo que tenho mais clareza na primeira que me explicita de a sensibiliza x**2...
Enfim, aí vem meu rant, um linter não semântico não consegue julgar isso. Prefiro deixar a regra em aberto a seguir uma regra que ignora legibilidade semântica.
Alinhamento
Agente prefere ferramentas à legibilidade, preferimos não quebrar o histórico do git, à seguir esse princípio.
Eu nunca vi um livro, cujo índice venha com o número após o título, e isso não é a toa, ajuda bastante a legibilidade.
De novo quebramos esse princípio tb por querer facilitar o trabalho da ferramenta.
Paralelismo/Repetição
Esse agente segue razoavelmente sempre criamos estruturas de dados recusáveis, adapters e coisas do tipo, mas uma coisa que não vejo linter nenhum fazer, e geralmente eu gosto de tentar seguir é dada uma mesma interface, de alguma forma expor as funções que cada adapter implementa, numa mesma ordem... Poxa isso ajuda bastante a leitura, principalmente qdo vc fica navegando entre um arquivo e outro, comparando um adapter e outro... Isso é lindo, mas não conheço linter que enforce isso, e vivo de boas com isso.
Não é pq o linter não consegue pegar uma regra que ela não deve ser seguida.
Contraste
Uma vez eu pensando em style guide de código vs princípios de design achei que não fazia sentido... Até eu me tocar disso quando percebi que um comentário meu onde eu escrevia em caps "HERE BE DRAGONS" me fez notar que isso é aplicação de contrate em style guide.
Comentar em tudo, quando não tem oq ser comentado é meio inútil, tanto quanto escrever tudo em caps.... Só incomoda.
Mas quando algo, que merece cuidado, atenção ou coisa parecida, comentário, as vezes gritante, até mesmo em caps e bem humorado destaca aquele conteúdo... E sim, comentar coisas desse tipo deveria fazer parte de um style guide... e de novo, não conheço um linter que consiga levantar esse ponto...
Em resumo
Só qdo tivermos uma AGI teremos ferramentas que conseguirão ser tão assertivas qto a styleguide qto queremos, existem contextos semânticos que não dá pra um linter avaliar.
Simplesmente ver como feature, escolher uma regra na qual o linter consegue inferir e seguir só por isso me soa muito ingênuo, é escolher ser guiado por um cego que anda sem bengala e só vai numa direção pq ele não sab virar pro lado.
Passamos a maior parte do nosso tempo lendo código (e discutindo sexo dos anjos no linter) eu não vejo razão em seguir um code style que não tem como objetivo facilitar isso: Leitura de codigo
Mas enfim, creio que preferimos ferramentas à legibilidade, vou me policiar e me forçar a não mais entrar nessas discussões pq minha produtividade vai a zero nisso.
Fico triste
@dalthon acho que estamos usando o linter com objetivos diferentes.
Linter não é para deixar o código mais bonito. Linter é para deixar o código uniforme.
Uma codebase como a nossa, apesar de escrita por diversas pessoas, tem que parecer escrita por uma única pessoa. Justamente por isso ele impõe regras que diminuem a chance de um mesmo código ser escrito de formas diferentes.
Imagina uma codebase onde eu encontre a mesma expressão (a * x) + b escrita das seguintes formas:
(a * x) + b
a * x + b
a*x + b
a*x+b
((a * x) + b)
a*x +b
a* x+ b
Isso dificulta a leitura pois precisamos adaptar nossa mente para interpretar coisas diferentes como iguais. Extrapolando o código, imagina se um país que emitisse moedas triangulares (isso existe) nossa mente não está acostumada com essa forma para moedas e ia causar uma estranheza.
Com o linter nosso código fica uniforme e deixamos essas preocupações e discussões de lado, focamos apenas na lógica e negócio.
PS: Neste styleguide também existem regras que eu não acho "bonitas" porém é a convenção dos desenvolvedores da Pagar.me e assim eu só as sigo.
https://github.com/pagarme/javascript-style-guide/issues/20#issuecomment-332807513 apesar das discussões fazerem vc parar de trabalhar no produto, ajuda/instrui e trás conhecimento e links para as pessoas que irão cair nas mesmas questões em breve. Gostei dos seus argumentos, sempre aprendo algo com vc :smiley_cat:
Vale lembrar que em casos extremos, você pode sim desabilitar o linter ou uma regra dele localmente em seu arquivo o que não pode ser sempre a solução, e isso de uma forma que sua equipe ache melhor, essa regra vale muito mais para desenvolvedores não tão experientes que irão fazer caquinha logo de primeira sem pensar duas vezes e sem querer.
O Linter também nos ajuda a se proteger de nós mesmos em alguns pontos, nesse quesito da Math no JS vc pegou no calcanhar haha there's no easy way.
Geralmente a gente começa com um linter muito extrito, e deixa que as pessoas tragam argumentos para melhora-lo.
O @MarcoWorms me falou exatamente isso essa semana:
Não é pq o linter não consegue pegar uma regra que ela não deve ser seguida.
@dalthon acho que vc tem muitos argumentos válidos, que tal se a gente reunisse pessoalmente o pessoal interessado nisso pra ver o que fazemos? Eu acho que é bem legal essa discussão sobre linter e qual é o papel dele no nosso trabalho.
@mccraveiro
@dalthon acho que estamos usando o linter com objetivos diferentes.
Linter não é para deixar o código mais bonito. Linter é para deixar o código uniforme.
No micro sim, no macro tlvz não estejamos muito longe não.
Não quero bonito, quero facilmente legível (inclua aí semanticamente legível).
Uniformidade se atinge seguindo um padrão, seja ele qual for, e nisso acho q todo mundo concorda em seguir. Minha birra é seguir um padrão zuado.
Pra mim, linter por si só, não garante beleza, legibilidade nem mesmo uniformidade. Vou no teu próprio exemplo:
Imagina uma codebase onde eu encontre a mesma expressão (a * x) + b escrita das seguintes formas:
a * x + b a*x + b a*x+b ((a * x) + b) a*x +b a* x+ b```
E adiciono mais casos que eu julgo ruim e me doem:
(x * a) + b
b + (x * a)
b + (a * x)
Quando se escreve algo que tem semântica de equação da reta, ou polinômio, esses três casos soam tão doloridos qto moeda triangular.
E pior, dependendo da semântica dos parâmetros, tlvz não seja positivo associar a eq da reta, pode ser q os nomes das variaveis estejam misleading... Será q faria sentido mudar o nome das variáveis? Será que não pq no dado contexto esses nomes poderiam trazer relevância? Enfim... linter nenhum resolve isso, sequer deixa isso uniforme.
Eu não sugiro desabilitar a regra pra cada um fazer como quer e fazer as bizarrices que foram citadas como contra exemplo de mau uso.
Muito pelo contrário.
Vale avaliar o significado real da bagaça qdo fazemos o review e questionar se está uniforme ou não... Mas no review, pq no linter agente baixa o nível de qualidade se limitando à ignorância dele.
Entre garantir zuado com o linter ou passar zuado despercebido em review, temos 2 opções:
- 100% de garantia de passar zuado com o linter ruim
- X porcento, com x ≤ 100 de passar despercebido na review
Eu, sem dúvida, prefiro a segunda.
@MarcoWorms topo, pretendo ir sexta para o escritório, mas acho q vale não limitar a presencial, caso alguém remoto queira dar pitaco.
Ps.: Esse tipo de discussão é que nem crack... Eu quero muito parar com ela mas tá difícil.
👍
Levantei a bola no #agile do slack pra ver se algum dos facilitadores bola uma cerimonia que ajude a gente a desviar do bike shedding e tentar chegar em alguma solução ;)
Galera, vamos agilizar essa discussão vai. Quem for a favor de remover essa regra vota com 👎 nesse comentário. Quem for a favor de manter como está vota com 👍 nesse comentário. Obrigado
Algo que não foi falado acima mas acho importante:
Desativando a rule space-infix-ops vamos permitir os seguintes casos:
a?b:c
const a={b:1}
let {a=0}=bar
function foo(a=0) { }
Se você votou aqui https://github.com/pagarme/javascript-style-guide/issues/20#issuecomment-333003382 agora confirme seu voto aqui.
Quem for a favor de manter como está vota com :-1: nesse comentário. Quem for a favor de remover essa regra vota com :+1: nesse comentário.