Comentários que ajudam, e os que atrapalham

O porquê vale mais que o quê

Existe uma crença de que quanto mais comentários, melhor o código, e ela é enganosa. O código já é a explicação do que o programa faz, escrita numa linguagem exata. Um comentário que apenas traduz o código de volta para o português, como um soma um ao contador em cima da linha contador recebe contador mais um, não agrega nada: ele diz o óbvio, ocupa espaço e ainda corre o risco de desatualizar. O comentário realmente valioso é o que explica algo que o código não consegue dizer sozinho: o porquê. Por que esse desconto é exatamente 12 por cento? Por que essa data foi tratada de forma especial? Por que essa ordem estranha de operações? O código mostra o que acontece; só um comentário do porquê preserva a intenção e o contexto por trás da decisão, que de outra forma se perderiam.

// RUIM (repete o quê): contador <- contador + 1  // soma 1 ao contador

// BOM (explica o porquê):
tentativas <- tentativas + 1
// bloqueia após 3 tentativas por exigência da política de segurança do banco
se tentativas >= 3 então
  bloquearConta()
fim

O comentário ruim repete o óbvio; o bom explica o porquê do número 3, que o código sozinho não revela.

O comentário que mente

Há um tipo de comentário pior que o inútil: o desatualizado. Comentários não são executados pelo computador, então nada obriga eles a acompanharem o código quando ele muda. Um programador ajusta a lógica, esquece de atualizar o comentário ao lado, e agora o comentário descreve algo que o código não faz mais. Quem lê confia no comentário, porque ele parece uma explicação oficial, e é induzido ao erro. Um código sem comentário te obriga a ler a lógica; um código com comentário errado te convence de uma mentira. Por isso, cada comentário é uma pequena dívida de manutenção: alguém precisa lembrar de atualizá-lo. A conclusão prática é comentar com parcimônia. Prefira deixar o código claro por si, com bons nomes e funções pequenas, e reserve os comentários para o porquê que realmente precisa ser registrado. Menos comentários, mais certeiros, envelhecem melhor.

Deixe o código falar por si

O ideal para o qual tudo neste módulo aponta é um código que se explica sozinho, precisando de poucos comentários porque a própria escrita é clara. Um trecho confuso com um comentário explicando o que ele faz muitas vezes pode virar um trecho claro sem comentário nenhum, só com melhores nomes e uma função bem batizada. Se você sente a necessidade de comentar o que uma linha faz, essa é frequentemente uma pista de que a linha poderia ser mais legível. Renomear uma variável, extrair um pedaço para uma função com nome descritivo, quebrar uma expressão complicada: essas mudanças costumam eliminar a necessidade do comentário, porque tornam a intenção óbvia no próprio código. Reserve os comentários para o que o código genuinamente não consegue dizer, o porquê, e deixe o resto da explicação por conta de nomes e estrutura claros. Esse equilíbrio, código que fala por si mais comentários certeiros de porquê, é a marca do código limpo maduro.