Eis uma pergunta que gosto de fazer a mim mesmo quando penso em adicionar um comentário em uma seção do código: O que posso transmitir para ajudar a próxima pessoa a entender melhor a intenção do código , para que eles possam atualizá-lo, corrigi-lo ou estendê-lo de maneira mais rápida e confiável?
Às vezes, a resposta correta para essa pergunta é que não há nada que você possa adicionar nesse ponto do código, porque você já selecionou nomes e convenções que tornam a intenção tão óbvia quanto possível. Isso significa que você escreveu um código sólido de autodocumentação e que inserir um comentário provavelmente prejudicaria mais do que ajudaria. (Observe que comentários redundantes podem realmente danificar a confiabilidade do código ao longo do tempo, diminuindo a falta de sincronia com o código real ao longo do tempo e, assim, dificultando a decifração da intenção real.
No entanto, em praticamente qualquer programa e em qualquer linguagem de programação, você encontrará pontos em que certos conceitos críticos e decisões tomadas pelo programador original - por você - não serão mais aparentes no código. Isso é praticamente inevitável porque um bom programador sempre programa para o futuro - ou seja, não apenas para fazer o programa funcionar uma vez, mas para fazer todos os seus muitos futuros consertos e versões e extensões e modificações e portas e quem sabe o que também funciona corretamente. Esse último conjunto de metas é muito mais difícil e requer muito mais raciocínio para fazer bem. Também é muito difícil expressar bem na maioria das linguagens de computador, que são mais focadas na funcionalidade - isto é, em dizer o que esta versão do programa precisa fazer, agora, a fim de torná-lo satisfatório.
Aqui está um exemplo simples do que quero dizer. Na maioria das linguagens, uma pesquisa rápida na linha de uma pequena estrutura de dados terá complexidade suficiente para que alguém que a analise pela primeira vez provavelmente não reconheça imediatamente o que é. Essa é uma oportunidade para um bom comentário, porque você pode adicionar algo sobre a intenção do seu código que um leitor tardio provavelmente apreciará imediatamente como útil para decifrar os detalhes.
Por outro lado, em linguagens como a linguagem baseada em lógica Prolog, expressar a busca de uma lista pequena pode ser tão incrivelmente trivial e sucinto que qualquer comentário que você possa adicionar seria apenas ruído. Então, bons comentários são necessariamente dependentes do contexto. Isso inclui fatores como os pontos strongs da linguagem que você está usando e o contexto geral do programa.
A questão é a seguinte: pense no futuro. Pergunte a si mesmo o que é importante e óbvio para você sobre como o programa deve ser entendido e modificado no futuro. [1]
Para as partes do seu código que são realmente auto-documentadas, os comentários adicionam ruído e aumentam o problema de coerência para versões futuras. Então não os adicione lá.
Mas para as partes do seu código em que você tomou uma decisão crítica de várias opções, ou onde o próprio código é complexo o suficiente para que seu propósito seja obscuro, por favor, adicione seu conhecimento especial na forma de um comentário. Um bom comentário, nesse caso, é aquele que permite a algum futuro programador saber o que deve ser mantido o mesmo - esse é o conceito de uma afirmação invariável, aliás - e o que é certo mudar.
[1] Isso vai além da questão dos comentários, mas vale a pena mencionar: se você perceber que tem uma ideia muito clara de como seu código pode mudar no futuro, provavelmente pensará além de apenas fazer um comentário e embutir esses parâmetros dentro do código em si, já que quase sempre será uma maneira mais confiável de garantir a confiabilidade de futuras versões do seu código do que tentar usar comentários para orientar uma pessoa futura desconhecida na direção certa. Ao mesmo tempo, você também quer evitar a generalização excessiva, já que os humanos são notoriamente ruins em prever o futuro, e isso inclui o futuro das mudanças no programa. Portanto, tente definir e captar dimensões razoáveis e comprovadas do futuro em todos os níveis do design do programa, mas não deixe que isso o distraia em um exercício de generalização excessiva que é improvável que se pague a longo prazo.