Comentar ou não comentar?

Postado por Abel Avram , traduzido por Pedro Mariano em 05 Mar 2010

Seções

Desenvolvimento,

Processos e Práticas,

Arquitetura e Design

Tópicos

Arquitetura ,

Programação ,

Entrega de Qualidade

Tags

Coding Standards

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?

1. Voltar ao topo

   "Programadores artistas" escrevem código legível

   por Prodis a.k.a. Fernando Hamasak...

   Na minha opinião, o que o Timo Hilden falou é uma grande bobagem.
   Um código que não é "autoexplicável" é um código ruim e não através de comentários que esse código deixará de ser ruim. Além disso, código que só um programador conhece vai totalmente contra a um ambiente colaborativo dentro de uma equipe de desenvolvimento.
   Mas o pior foi o "programador artista", que deve respeitar sua audiência, os outros membros da equipe. O fato de enfiar um monte de comentário no código ao invés de escrevê-lo de forma intuitiva e com "linguagem ubíqua", isso sim é desrespeitar "sua audiência".

   Responder

2. Voltar ao topo

   Re:

   por Pedro Henrique Santana Mariano

   Concordo com o que você disse Fernando. Mas e sobre escrever comentários para que, em um futuro, você possa lembrar o "para que esse código foi escrito" ? Concordo que os códigos deveriam ler legíveis, mais ocorre, que em algumas linguagens, isso se torna meio que inviável devido as limitações por ela imposta, o que você acha?

   Responder

3. Voltar ao topo

   ??

   por Aluisio Vanzolin

   Não comentar códigos, significa programar pra vc mesmo. Só tem vc na empresa ? Se sim, ótimo. Vc sabe o q faz. Se não, é um problema. Comentar um código significa saber bem o q vc está programando e ainda dar um breve explicativo para o próximo q for usá-lo, ou modificá-lo, possa saber só de bater o olho o q está sendo feito.
   Q negócio é esse de escrever código entre o comentário de o código ??
   A empresa q o cara trabalha tem mesmo programadores ?? Ou são só gambiarradores ??

   Responder

• Mais antigos >