A maioria dos desenvolvedores já escreveu pelo menos uma linha de comentário em seu código. Alguns cheam até a escrever várias linhas de comentário com o intuito de tornar o explicar melhor o que tal implementação faz. Esse artigo reúne algumas práticas usadas na hora de escrever comentários, além de opiniões internacionais e nacionais sobre comentar o seu código.
Os membros do grupo Seattle Area Alt.Net vêm discutindo as necessidades e práticas para escrever comentários. Kelly Leahy prefere um código autoexplicativo com pouquissímos comentários, isso porque ele acredita que comentários "oferecem algumas informações erradas no sistema" pois tendem a " serem esquecidos quando há alguma alteração no código":
[escrever comentários] é algo pessoal para várias pessoas, mas eu tenho uma forte tendência a ir contra comentários, por causa da propensão de ficarem esquecidos quando há alguma alteração no código - Eu já vi isso acontecer tantas vezes, quando algum comentário que se refere a um código que não existe mais, código que não vem imediatamente depois dos comentários ( porque alguém inseriu uma nova linha de código entre o comentário e o código original) ou comentários que afirmar algo que não é mais verdade, isso por que o código foi alterado mais os comentários foram deixados para trás.
Eu acho que a existência de comentários em situações parecidas com as citadas acima, que eu abomino completamente, são muito piores do que a falta deles.
Leahy não exclui completamente os comentários e diz que usa uma linha de comentário para cerca de 10.000 linhas de código:
Comentários podem, algumas vezes, serem úteis quando você possui regras em seu design que não podem ser esquecidas esse tipo de coisa requer um pouco mais de explicação. Eu tenho evitado comentar meu código, e aqui nós provavelmente temos 1 linha de comentário para cada 10.000 ou mais linhas de código ( exceto os clássicos comentários do xmldoc, que eu particulamente acho desnecessário em uma API pública).
Justin Rudd explicou que ele precisava de muitos comentários em seu código pois a API era "muito confusa":
Agora eu estou escrevendo um controlador de pacotes para o Visual Studio. Essa API é tão confusa que eu escrevi comentários para poder lembrar porque em tal lugar eu passei o Guid.Empty e em outro eu passei um GUID particular.
Eu comento qual das 4 soluções estou implementando no momento então quando a próxima pessoa vê 6 dos 7 métodos implementados ela vai saber que não pode deletar o que está sendo implementado.
Eu comento por que eu retorno um HRESULT de um método por que se eu retornasse S_OK o Visual Studio iria travar.
Chris Tavares utiliza comentários para correção de bugs:
O comentário "// isso foi feito para corrigir o bug #####" não é feio - de fato ele é essencial.
Já Brandon Molina acredita que é melhor utilizar o seu sistema de controle de versão para comentar correções de bugs ao invés de deixar o mesmo dentro de seu código:
O que acontece quando você conserta 10 bugs? O código está atualizado e agora você tem um cerca de um paragráfo desnecessário bagunçando o seu código. Use o sistema de controle de versão para isso. O comentário deveria ser a informação de um diff, que em fim, contém informação útil para o que foi feito.
Bras Wilson introduz uma regra para evitar a escrita de péssimos comentários:
Comentários que explicam o "Por que" == bom
Comentários que explicam "Como" == não muito bom
Ao escrever comentários de código, Timo Hilden enfatiza a necessidade de se incluir bons comentários:
É muito fácil deixar de escrever comentários de código. Vamos exemplificar isso, nós somos desenvolvedores e não iremos ganhar o prêmio Pulitzer por isso, então isso não é algum problema de habilidade pessoal ou dificuldade de expressão, isso é apenas preguiça.
Para ser honesto, deixar deixar o código sem um comentário descritivo quando necessário é muito pior do que parece. Primeiramente, isso mostra de forma indireta a falta de respeito do programador com os seus parceiros. Todo mundo sabe o quão frustrante é quando você se depara com um monte de classes cheia de métodos complexos em um código que não é autoexplicável, especialmente se o programador que fez o código saiu de férias, saiu da empresa ou não está disponível por alguma razão. Um programador é um artista, enquanto os outros programadores são a audiência.E como todo artista, devemos respeitar a nossa audiência.
Em segundo lugar, não escrever comentários mostra que o programador não desconfia de algumas atitudes de si mesmo. Quando estamos escrevendo algum código, nós geralmente temos uma idéia do que nós estamos implementando. Mas na programação acontece muito de você esquecer detalhes do que foi feito, ou até esquecer o que foi feito, da próxima vez que você olhar o código você sentirá dificuldade para entender e para relembrar toda a idéia original. Nessa situações, que são comuns, comentários descritivos poderiam ser úteis.
Hilden não concorda com a falsa documentação (undocummented) - uma prática mencionada por Scott Swigart e Jeff Atwood anos atrás -, considerando os exemplos abaixo como documentação excessiva:
//Declara id da categoria para os produtos const int prodCategoryId = 1024; //Cria um iterador sobre os produtos vector::iterator iter = products_.begin();
//Itera sobre todos os produtos
for ( ; iter != products_.end(); ++iter )
{
//Atribui o id da categoria para cada produto
iter->AssignCategoryId( prodCategoryId );
}
Ele sugere combinar todos os comentários acima gerando uma idéia geral e não explicando cada etapa:
//Atribui um id de categoria para cada produto
const int prodCategoryId = 1024;
vector::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}
O brasileiro Rodrigo Urubatan, possui um post em seu blog intitulado "Comentário no código é para os fracos" onde ele diz:
Só para constar, eu não acho de verdade que vocês não devem comentar o código, mas se vocês não escrevem código legível, ou escrevem código que realmente precisa de um comentário para outro programador entender, então vocês não aprenderam a programar ainda!
Vínicius Maia tem a visão a longo prazo vendo comentários como uma forma de relembrar a implementação, além de darem um ar mais profissionalismo ao código:
Apesar do grande desgosto em se fazer documentação de código, a implementação deste, é muito importante. Só a existência da documentação já dá um ar mais profissional ao código, mas a principal vantagem está em informar como determinada parte do código funciona, se outro programador for trabalhar no código, ele não vai ficar perdido e se depois de 3 anos você olhar pra teu código novamente, os comentarios te ajudarão a relembrar para que serve cada parametro e como a função se comporta.
Você vê necessidade de se comentar o código? Quais práticas para escrever código você utiliza? Essas práticas são requisitos da sua empresa ou você mesmo que escolheu utiliza-lás? Você utiliza a prática de escrever uma quantidade mínima de comentários, para que o próximo desenvolvedor entenda o seu código, ou você acha que é responsábilidade do próximo desenvolvedor documentar o que ele não achou óbvio?