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 ap