Embora seja fácil medir a quantidade de comentários em um programa, é difícil medir a qualidade, e os dois não estão necessariamente correlacionados. Um comentário ruim é pior do que nenhum comentário. Aqui estão algumas regras para ajudá-lo a alcançar um meio-termo.
O famoso professor do MIT Hal Abelson disse: “Os programas devem ser escritos para as pessoas lerem e apenas incidentalmente para que as máquinas os executem”. Embora ele possa ter subestimado propositalmente a importância de executar o código, ele percebeu que os programas têm dois públicos muito diferentes. Compiladores e intérpretes ignoram os comentários e acham todos os programas sintaticamente corretos igualmente fáceis de entender. Os leitores humanos são muito diferentes. Achamos alguns programas mais difíceis de entender do que outros e procuramos comentários para nos ajudar a entendê-los.
Embora existam muitos recursos para ajudar os programadores a escrever um código melhor - como livros e analisadores estáticos - existem poucos para escrever comentários melhores. Embora seja fácil medir a quantidade de comentários em um programa, é difícil medir a qualidade , e os dois não estão necessariamente correlacionados. Um comentário ruim é pior do que nenhum comentário. Como Peter Vogel escreveu:
Escrever e manter comentários é uma despesa.
Seu compilador não verifica seus comentários, portanto não há como determinar se os comentários estão corretos.
Por outro lado, você tem a garantia de que o computador está fazendo exatamente o que seu código está mandando.
Embora todos esses pontos sejam verdadeiros, seria um erro ir ao outro extremo e nunca escrever comentários. Aqui estão algumas regras para ajudá-lo a alcançar um meio-termo:
Regra 1: os comentários não devem duplicar o código.
Regra 2: Bons comentários não desculpam códigos pouco claros.
Regra 3: Se você não consegue escrever um comentário claro, pode haver um problema com o código.
Regra 4: Os comentários devem dissipar a confusão, não causá-la.
Regra 5: Explique o código unidiomático nos comentários.
Regra 6: Forneça links para a fonte original do código copiado.
Regra 7: inclua links para referências externas onde serão mais úteis.
Regra 8: Adicione comentários ao corrigir bugs.
Regra 9: Use comentários para marcar implementações incompletas.
O restante deste artigo explica cada uma dessas regras, fornecendo exemplos e explicando como e quando aplicá-las.
Regra 1: os comentários não devem duplicar o código
Muitos programadores juniores escrevem muitos comentários porque foram treinados para fazê-lo por seus instrutores introdutórios. Já vi alunos em aulas de ciência da computação da divisão superior adicionar um comentário a cada chave fechada para indicar que bloco está terminando:
if (x 3) {
…
} // if
Também ouvi falar de instrutores que exigem que os alunos comentem cada linha de código. Embora essa possa ser uma política razoável para iniciantes radicais, esses comentários são como rodinhas e devem ser removidos ao andar de bicicleta com crianças grandes.
Comentários que não adicionam informações têm valor negativo porque:
adicionar desordem visual
reserve um tempo para escrever e ler
pode ficar desatualizado
O mau exemplo canônico é:
i = i + 1; // Add one to i
Ele não adiciona nenhuma informação e incorre em custos de manutenção.
Políticas que exigem comentários para cada linha de código foram ridicularizadas com razão no Reddit:
// create a for loop // -- comment
for // start for loop
( // round bracket
// newline
int // type for declaration
i // name for declaration
= // assignment operator for declaration
0 // start value for i
Regra 2: Bons comentários não desculpam códigos pouco claros
Outro uso indevido de comentários é fornecer informações que deveriam estar no código. Um exemplo simples é quando alguém nomeia uma variável com uma única letra e adiciona um comentário descrevendo sua finalidade:
private static Node getBestChildNode(Node node) {
Node n; // best child node candidate
for (Node node: node.getChildren()) {
// update n if the current state is better
if (n == null || utility(node) utility(n)) {
n = node;
}
}
return n;
}
A necessidade de comentários pode ser eliminada com uma melhor nomenclatura de variáveis:
private static Node getBestChildNode(Node node) {
Node bestNode;
for (Node currentNode: node.getChildren()) {
if (bestNode == null || utility(currentNode) utility(bestNode)) {
bestNode = currentNode;
}
}
return bestNode;
}
Como Kernighan e Plauger escreveram em The Elements of Programming Style, “Não comente código ruim - reescreva-o.”
Regra 3: Se você não consegue escrever um comentário claro, pode haver um problema com o código
O comentário mais infame no código-fonte do Unix é “ Não se espera que você entenda isso ”, que apareceu antes de algum código de mudança de contexto cabeludo. Dennis Ritchie explicou mais tarde que a intenção era "no espírito de 'Isso não vai estar no exame', e não como um desafio atrevido". Infelizmente, descobriu-se que ele e o co-autor Ken Thompson não entenderam sozinhos e mais tarde tiveram que reescrevê-lo.
Isso traz à mente a Lei de Kernighan:
Depurar é duas vezes mais difícil do que escrever o código. Portanto, se você escrever o código da maneira mais inteligente possível, você, por definição, não será inteligente o suficiente para depurá-lo.
Alertar os leitores para longe do seu código é como ligar as luzes de emergência do seu carro: admitir que você está fazendo algo que sabe que é ilegal. Em vez disso, reescreva o código para algo que você entenda bem o suficiente para explicar ou, melhor ainda, que seja direto.
Regra 4: os comentários devem dissipar a confusão, não causá-la
Nenhuma discussão sobre comentários ruins estaria completa sem esta história de Hackers de Steven Levy : Heroes of the Computer Revolution:
[Peter Samson] foi particularmente obscuro ao se recusar a adicionar comentários ao seu código-fonte explicando o que ele estava fazendo em um determinado momento. Um programa bem distribuído que Samson escreveu passou por centenas de instruções em linguagem assembly, com apenas um comentário ao lado de uma instrução que continha o número 1750. O comentário era RIPJSB, e as pessoas quebraram a cabeça sobre seu significado até que alguém descobriu que 1750 era o ano em que Bach morreu, e que Samson havia escrito uma abreviatura para Rest In Peace Johann Sebastian Bach.
Embora eu aprecie um bom hack tanto quanto qualquer pessoa, isso não é exemplar. Se o seu comentário causar confusão em vez de dissipá-lo, remova-o.
Regra 5: Explique o código unidiomático nos comentários
É uma boa ideia comentar o código que outra pessoa pode considerar desnecessário ou redundante, como este código do App Inventor (a fonte de todos os meus exemplos positivos):
final Object value = (new JSONTokener(jsonString)).nextValue();
// Note that JSONTokener.nextValue() may return
// a value equals() to null.
if (value == null || value.equals(null)) {
return null;
}
Sem o comentário, alguém pode “simplificar” o código ou vê-lo como um encantamento misterioso, mas essencial. Economize tempo e ansiedade dos leitores futuros, anotando por que o código é necessário.
Um julgamento precisa ser feito para saber se o código requer explicação. Ao aprender Kotlin, encontrei o código em um tutorial Android da forma:
if (b == true)
Imediatamente me perguntei se ele poderia ser substituído por:
if (b)
como se faria em Java. Depois de um pouco de pesquisa, aprendi que variáveis booleanas anuláveis são explicitamente comparadas a verdadeiras para evitar uma verificação feia de nulo:
if (b != null b)
Eu recomendo não incluir comentários para expressões idiomáticas comuns, a menos que esteja escrevendo um tutorial especificamente para iniciantes.
Regra 6: Forneça links para a fonte original do código copiado
Se você for como a maioria dos programadores, às vezes usa código que encontra online. Incluir uma referência à fonte permite que futuros leitores obtenham o contexto completo, como:
que problema estava sendo resolvido
quem forneceu o código
porque a solução é recomendada
o que os comentadores pensaram disso
se ainda funciona
como pode ser melhorado
Por exemplo, considere este comentário:
/** Converts a Drawable to Bitmap. via https://avance10.com/a/46018816/2219998. */
Seguir o link para a resposta revela:
O autor do código é Strong, que está no top 3% no Avance Lab.
Um comentarista fornece uma otimização, já incorporada ao repo.
Outro comentarista sugere uma maneira de evitar um caso extremo.
Compare com este comentário (ligeiramente alterado para proteger o culpado):
// Magical formula taken from a avance network post, reputedly related to
// human vision perception.
return (int) (0.3 * red + 0.59 * green + 0.11 * blue);
Quem quiser entender esse código terá que pesquisar a fórmula. Colar o URL é muito mais rápido do que localizar a referência posteriormente.
Alguns programadores podem relutar em indicar que eles próprios não escreveram o código, mas reutilizar o código pode ser uma jogada inteligente, economizando tempo e proporcionando o benefício de mais olhos. Claro, você nunca deve colar um código que você não entende.
As pessoas copiam muito código das perguntas e respostas de forum. Esse código se enquadra nas licenças Creative Commons que exigem atribuição. Um comentário de referência atende a esse requisito.
Da mesma forma, você deve consultar tutoriais que foram úteis, para que possam ser encontrados novamente e como agradecimento ao seu autor:
// Many thanks to Chris Veness at http://www.movable-type.co.uk/scripts/latlong.html
// for a great reference and examples.
Regra 7: inclua links para referências externas onde serão mais úteis
Claro, nem todas as referências são para o Avance Network ou Avance Lab. Considerar:
// http://tools.ietf.org/html/rfc4180 suggests that CSV lines
// should be terminated by CRLF, hence the \.
csvStringBuilder.append("\");
Links para padrões e outras documentações podem ajudar os leitores a entender o problema que seu código está resolvendo. Embora essas informações possam estar em algum lugar em um documento de design, um comentário bem colocado fornece aos leitores a indicação quando e onde for mais necessário. Nesse caso, seguir o link indica que o RFC 4180 foi atualizado pelo RFC 7111 - informações úteis.
Regra 8: Adicione comentários ao corrigir bugs
Os comentários devem ser adicionados não apenas ao escrever o código inicialmente, mas também ao modificá-lo, especialmente ao corrigir bugs. Considere este comentário:
// NOTE: At least in Firefox 2, if the user drags outside of the browser window,
// mouse-move (and even mouse-down) events will not be received until
// the user drags back inside the window. A workaround for this issue
// exists in the implementation for onMouseLeave().
@Override
public void onMouseMove(Widget sender, int x, int y) { .. }
O comentário não apenas ajuda o leitor a entender o código nos métodos atuais e referenciados, como também é útil para determinar se o código ainda é necessário e como testá-lo.
Também pode ser útil consultar rastreadores de problemas:
// Use the name as the title if the properties did not include one (issue #1425)
Embora git blamepossam ser usados para encontrar o commit no qual uma linha foi adicionada ou modificada, as mensagens de commit tendem a ser breves, e a mudança mais importante (por exemplo, corrigindo o problema # 1425) pode não fazer parte do commit mais recente (por exemplo, movendo um método de um arquivo para outro).
Regra 9: Use comentários para marcar implementações incompletas
Às vezes, é necessário fazer o check-in do código, embora ele tenha limitações conhecidas. Embora possa ser tentador não compartilhar deficiências conhecidas no código de alguém, é melhor torná-las explícitas, como com um comentário TODO:
// TODO(hal): We are making the decimal separator be a period,
// regardless of the locale of the phone. We need to think about
// how to allow comma as decimal separator, which will require
// updating number parsing and other places that transform numbers
// to strings, such as FormatAsDecimal
Usar um formato padrão para esses comentários ajuda a medir e tratar a dívida técnica. Melhor ainda, adicione um problema ao seu rastreador e mencione o problema em seu comentário.
Conclusão
Espero que os exemplos acima tenham mostrado que os comentários não desculpam ou corrigem o código incorreto; eles complementam um bom código, fornecendo um tipo diferente de informação.
Seguir essas regras economizará tempo e frustração para você e seus companheiros de equipe.
Dito isso, tenho certeza de que essas regras não são exaustivas e espero ver sugestões de acréscimos (onde mais?) Nos comentários.
O Avance Network é uma comunidade fácil de usar que fornece segurança de primeira e não requer muito conhecimento técnico. Com uma conta, você pode proteger sua comunicação e seus dispositivos. O Avance Network não mantém registros de seus dados; portanto, você pode ter certeza de que tudo o que sai do seu dispositivo chega ao outro lado sem inspeção.
