Como escrever bons comentários de código: "por que", não "como"

Olá, Habr! Apresento a sua atenção a tradução do artigo "Escrevendo bons comentários: o porquê, não o como" de Jack Franklin.







Comentar o código em um ambiente de programação é frequentemente considerado uma perda de tempo ou um sinal de que o código pode ser melhorado. Aqui está uma citação do arquivo CONTRIBUTING.md que encontrei no GitHub (e há muitos desses exemplos):

Comentários devem ser evitados. Se o seu código não pode ser entendido sem comentários, reescreva-o para se explicar.

Acredito que, na maioria dos casos, tais conselhos serão malsucedidos e incorretos. Essa abordagem, acredito, tem suas raízes nas experiências de aprendizagem da maioria das pessoas que estudaram programação. Quando estudei ciência da computação na universidade (embora este conselho possa ser encontrado em muitos cursos, não necessariamente nos universitários), lembro-me muito no primeiro semestre de um professor que disse:

Cada linha de código deve ter um comentário explicando o que ela faz. Seu trabalho no curso será julgado de acordo com este critério.

Então, digamos que você seja um aluno recém-saído do forno apenas começando este curso. O que você vai fazer? Comente o código, claro!

//      bar
const inputValue = process.ENV.bar

//     2
const newValue = inputValue * 2

//     square
const finalValue = square(newValue)

//         
const square = (x) => x * x

Pessoas que dizem que os comentários são ruins, na verdade estão pensando em comentários como este. E eles estão absolutamente certos! Comentários como os anteriores, respondendo à pergunta “como?” Em programação, são completamente inúteis. Todos esses comentários não adicionaram nada ao código que não possa ser compreendido pelo próprio código.

Responda à pergunta "por quê?"

O problema com os comentários acima é que eles explicam como . Explica as etapas que executamos no código. Esses comentários raramente são úteis; o código em si é muito melhor para lhe dizer o que fazer. Afinal, as linhas de código são apenas instruções que informam ao computador como concluir uma tarefa.



Normalmente, não há necessidade de muitos comentários, porque você pode escrever um código simples sem recursos ou nuances que dariam a ele uma aparência incompreensível. Mas às vezes surgem situações em que é impossível escrever código elementar e intuitivo. Talvez seja um bug que você precisa contornar. Ou você herdou a felicidade de desenvolvedores anteriores na forma de um sistema que o impede de resolver o problema da maneira que gostaria. Ou, no final do dia, simplesmente não há maneira fácil de melhorar seu código.



Uma vez trabalhei em uma empresa de processamento. Todos os dias executávamos uma enorme consulta SQL que selecionava os pagamentos a serem pagos. A consulta foi bem otimizada - precisávamos que fosse muito rápida - e extremamente complexa: havia muitos casos extremos a serem considerados. Tentamos ao máximo deixar isso o mais claro possível. No entanto, essa solicitação nunca poderia ser totalmente intuitiva e fácil de entender. Ele simplesmente continha muito código com um monte de condições e lógicas que só podiam ser entendidas no contexto de nossa empresa e como funcionava.



Eu queria encontrar um exemplo para mostrar aqui, então entrei na selva da base de código do React para encontrar algo. Você não precisa ser um desenvolvedor React para descobrir isso. Então, aqui está o código que eu gostaria de destacar:

//  key     .    , 
//  key      (, <div {...props} key="Hi" />
//  <div key="Hi" {...props} /> ).     key,   ,
//      jsxDEV   , 
// <div {...props} key="Hi" />,       ,
//    key   . 
if (maybeKey !== undefined) {
  key = '' + maybeKey
}

( E aqui está um link para ele no GitHub ).



Preste atenção ao próprio código:

if (maybeKey !== undefined) {
  key = '' + maybeKey
}

Não é tão difícil descobrir o que isso faz. Se MaybeKey não for especificado, atribuímos o valor stringified MaybeKey para key. Nota: Este é um pequeno truque de JavaScript para '' + maybeKeyconverter o conteúdo de MaybeKey em uma string.



Mas aqui toda a questão é sobre o porquê . O comentário para este código é ótimo. Ele aponta o problema, dá dois exemplos e também explica como resolver esse problema no longo prazo e o que estamos fazendo no curto prazo.



Se você quiser ver qualquer comentário que deixei no código que escrevi, aqui está um (TypeScript / Closure Compiler) . Este é um bom exemplo do tipo de comentários que considero muito valiosos.



No final, qualquer código pode ser entendido. Afinal, o código nada mais é do que instruções que informam ao computador como proceder. O código pode ser confuso, mas não pode mentir; se o tempo for suficiente, qualquer desenvolvedor pode percorrer o código passo a passo e entender o que ele está fazendo. Às vezes é muito mais difícil entender por que ele faz isso. Portanto, deixe seus colegas de trabalho (ou futuro-você-seis-meses a partir de agora) algum contexto sobre por que e para que seu código faz o que faz. Vai ficar muito melhor.