Comentar ou não comentar, eis a questão

shakespeare Comentários de código, a exemplo de qualquer outra prática de desenvolvimento, podem contribuir ou atrapalhar o projeto dependendo do uso. Assim como o próprio código os comentários precisam de manutenção ao longo do ciclo de desenvolvimento. Isto gera um custo de manutenção do comentário e o risco deles contradizerem o código, caso seja feita uma mudança no código e o comentário não seja atualizado.

Logo, é importante discernir quando um comentário deve ou não ser inserido no código. Neste artigo eu categorizo alguns tipos de comentários, e discuto a importância de cada um.

Comentários Escola

Comentários escola são aqueles que se propõem a ensinar conhecimentos primários para o leitor, como conceitos de programação e palavras em inglês. Apesar de não serem úteis, esse é o um tipo de comentário muito comum. Evite escrever estes tipos de comentário, pois eles só poluem o código. Abaixo mostro alguns exemplos, inspirados em projetos reais :):

Aulas de inglês

// Cliente
class Customer  
{
    // Data de nascimento
    Date birthDate;

    // Idade
    int age;

    // Nome
    String name;

    // Endereço
    Address address;
}

Aulas de programação

// Para cada item na lista
for ( item : lista )  
{
   // Incrementa a variável a
   a++
}

// Se tem garantia
if ( temGarantia )  
{
   ...
}

Às vezes a qualidade das aulas são comparáveis a das escolas municipais do Rio. Acredite, o caso abaixo realmente aconteceu:

// Retorna verdadeiro
return false;  

Comentários Desodorante

Comentários desodorante são aqueles que tentam aliviar o mau cheiro de um determinado bloco de código, tentando explicar o que o código faz.. Neste caso o comentário tem o objetivo de facilitar a leitura do código difícil. Apesar da idéia parecer boa a princípio, para a saúde do código seria melhor que o trecho fosse reescrito de forma a melhorar sua legibilidade. Com um código naturalmente "cheiroso" o comentário desodorante pode ser dispensado.

Sempre que pensar em incluir um comentário para explicar o que o código faz, tente descobrir formas de deixar mais clara a intenção do código pelo próprio código. Para ajudar neste processo, algumas leituras podem ser úteis [1].

Seguem abaixo alguns exemplos de códigos com comentários desodorante e uma versão deste código que dispensa estes comentários [2]:

Com comentário

void geraCartaoMetro( Cliente cliente )  
{
    // Verifica se cliente possui gratuidade (idoso ou deficiente)
    if ( cliente.idade() > 65 || cliente.deficiente() ) 
        ...
}

Dispensa comentário

void geraCartaoMetro( Cliente cliente )  
{
    if ( possuiGratuidade( cliente ) )
        ...
}

boolean possuiGratuidade( cliente )  
{
    return cliente.idoso() || cliente.deficiente() 
}

Ou um ou outro

Às vezes esse princípio é usado como desculpa para continuar escrevendo código ruim e não comentar. Nesse caso é melhor comentar, afinal um código fedido perfumado é melhor que um código fedido fedido.

Comentários que revelam o mistério dos porquês

Eu já me deparei com códigos bem escritos, onde conseguia entender perfeitamente o que o código fazia, mas não conseguia entender porque ele fazia. Tratam-se de blocos de código que contornam bugs de frameworks, motivados por regras de negócio obscuras ou simplesmente coisas que não ficam claras olhando só para o código.

Neste caso para o código fazer sentido é importante entender sua motivação. Estas situações não são raras, e os comentários podem vir bem a calhar. Abaixo seguem alguns exemplos:

// Temos que mover para uma pasta temporária antes de processar para evitar que o arquivo seja processado duas vezes em caso de concorrência
for ( arquivo : arquivos )  
{
    arquivo.moveParaPastaTemporaria();
}
// O compareTo da classe date não funciona direito, por isso implementamos o nosso: http://bugs.sun.com/bugdatabase/view_bug.do?bug_id=5103041
int compareTo( Date data, Date outraData )  
{
 ...
}

Não responda essa pergunta pelos outros

Muitos comentários ruins acontecem quando a resposta de quando comentar é respondida de forma automática por outra pessoa ou pela empresa. Normalmente isso acontece através de políticas que obrigam comentários em determinados métodos ou classes ou uma percentagem de comentários por linha de código. Isso frequentemente gera comentários redundantes (como o de getters e setters) e outros casos estranhos citados aqui.

Viver é preciso

O aprendizado do uso correto de comentários vem com a experiência, especialmente a partir da leitura de códigos de terceiros ou mesmo dos próprios, algum tempo após escritos. Nestas horas percebemos a irrelevância dos comentários redundantes e a falta dos importantes.


[1] http://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882, http://www.amazon.com/Refactoring-Improving-Design-Existing-Code/dp/0201485672
[2] Agradecimento a Carlos Bonfim pelos exemplos