Existe uma cultura entre os programadores na qual a máxima ‘use comentários sempre que puder e deixe seu código bem explicado’ é praticamente uma lei fundamental da programação. Pouca gente discute isso, afinal, nada como um código bem documentado para torná-lo legível, certo? Nem sempre. E é sobre esta questão que eu vou falar neste artigo. Quando devemos usar comentários? Até que ponto comentar é uma boa prática? Existem outros artifícios que podemos usar para substituir um comentário?

Para começar, vamos voltar um pouco pela história. Há muito tempo, os compiladores tinham uma limitação de memória, onde existia um limite de caracteres por arquivo compilável. Em consequência disso, os programadores eram obrigados a serem muito seletivos e econômicos ao codificar, usando o menor número de caracteres para nomes de operações, variáveis e etc. Imagine um complexo código de ordenação onde todas as variáveis tivessem apenas um caractere. A primeira variável seria a variável ‘a’, a segunda ‘b’, a terceira ‘c’. Qual seria sua reação, ao ‘tentar’ ler esse código? Um pouco confuso, provavelmente. Nessa hora qualquer um rezaria por encontrar um código bem comentado.

Integer a = 0; //armazena o maior valor encontrado

Nota-se que a origem dos comentários teve motivações bem legítimas, e eram praticamente indispensáveis.

Desde então, os compiladores evoluíram, o hardware mudou muito, e hoje, finalmente, não temos problema algum relacionado a limite de memória (pelo menos não significativamente) que nos limite na hora de codificar. Porém, muito da antiga cultura ainda permaneceu. Programadores mais antigos não abriram mão de suas variáveis de um caractere e continuam usando comentários para explicá-las, influenciando muitos os novos programadores, e nem todos conseguem chegar a um nível de maturidade suficiente para superar esse limite auto imposto.

Veja como, na linha abaixo, o comentário torna-se desnecessário, ao contrário do código anterior.

Integer maiorValor = 0; //armazena o maior valor encontrado

Como não temos mais o limite de memória, fica fácil nomear a variável de forma a um comentário se tornar insignificante. Uma outra questão também deve ser citada: temos mais facilidade em descrever uma coisa do que dar nomes. Talvez por isso muitos programadores preferem comentar a ter que pensar em um nome que descreva o motivo da variável, função, classe e etc. Mas, mesmo assim, um bom nome é melhor e deixa o código mais fácil de ser lido e entendido. Vale a pena investir mais tempo para elaborar melhor os nomes em seu código.

Martin Fowler costuma dizer que, se seu código precisa de comentários para ser entendido, então é porque ele não está bem escrito. Essa idéia está presente também nessa outra frase bem conhecida, também de sua autoria.

Qualquer tolo pode escrever código que um computador pode compreender, mas bons programadores escrevem códigos que os seres humanos possam compreender. [Fowler 2000]

É lógico que não podemos ser extremistas a ponto de abolir os comentários do nosso código. Muito pelo contrário. Existem ocasiões – não raras – onde comentar é essencial ou, no mínimo, construtivo.

/*usei int p/ manter compatibilidade com uso da dll xz.dll*/

int indice;

Antes de comentar uma linha, devemos sempre nos perguntar se o comentário agrega algo, ou se apenas tenta desfazer a confusão que foi gerada pelo código. Como insistirei frequentemente daqui pra frente: bom senso é sempre fundamental.

Atualmente, como parte dos estudos dos princípios Grasp (abordarei o que é Grasp aqui no AgileZ em breve), na equipe em que trabalho, adotamos o costume de documentar a ‘motivação’ que levou uma classe a ser desenvolvida, usando para isso um comentário – de no máximo umas 3 linhas – que explica o motivo da classe existir. Isso, como veremos em artigos futuros, é bem interessante e é parte de uma metodologia adotada por nossa equipe.

Passou longe do objetivo deste breve artigo a intenção de esgotar o assunto. Pretendo voltar discutir a questão de comentários no código quando falar sobre refatoração e também sobre usabilidade aplicada a codificação. Continuem ligados.