Clean Code (Código limpo) – Comentários

Nada pode ser mais útil que um comentário bem feito. Nada pode ofuscar mais um modulo que comentários inúteis e, nada vai causar mais danos que comentários antigos que propagam mentiras e desinformação.

Quanto mais velho o comentário, e quanto mais longe está do código que ele descreve as chances são de que está errado. A causa para isso é simples, programadores não conseguem realisticamente mantê-los atualizados.

Comentários são, em seu melhor caso, um mal necessário.

Uma forma simples de expor os pesamentos sobre eles é “Comentários são sempre falhas”. Nós devemos tê-los, porque não podemos sempre descobrir como nos expressar sem eles, mas usá-los não é motivo de celebração.

Todas as vezes que você conseguir se expressar usando seu código, você pode se regozijar, e todas as vezes que escrever um comentário você deve sentir o peso da falha em sua habilidade de se expressar.Comentários imprecisos são piores que os inexistentes. Eles enganam e setam expectativas que nunca serão cumpridas. Eles normalmente descrevem velhas regras que não deveriam ou não são seguidas.

Importante lembrar que a verdade somente pode ser encontrada em um lugar, no código, não importa o que diz o comentário.

Comentários não compensam por código ruim

O motivo mais comum para escrever comentários é código ruim. Então em vez de gastar seu tempo escrevendo comentários, gaste seu tempo arrumando a bagunça.

Explique-se usando o código

Em muitos casos, é uma simples questão de criar uma função que diz a mesma coisa que o comentário que você deseja escrever.

Ruim

// check if the user is available
if( user.Staus = 1 && user.LastAccess < DateTime.Now.AddDays(-30))

Bom

if( user.IsAvailable() )

Bons comentários

Alguns comentários são necessários ou benéficos. Veremos alguns que o autor considera digno dos bits que consomem. Tenha em mente, no entanto, que o único comentário realmente bom é aquele que você encontrou uma maneira de não escrever.

Comentários obrigatórios são bons

Às vezes, empresas nos obrigam a escrever certos comentários por motivos legais. Por exemplo, direitos autorais e de autoria. Estes comentários normalmente estão no início do código e por serem obrigatórios não temos poder sobre eles.

Comentários informativos são bons

// format matched dd/mm/yyyy
^(?:[012]?[0-9]|3[01])[./-](?:0?[1-9]|1[0-2])[./-](?:[0-9]{2}){1,2}$

Neste caso, o comentário nos permite saber que a expressão regular se destina a corresponder a uma data que foi formatada, este tipo de comentário é uma faca de dois gumes, pois se a expressão for atualizada e o comentário ficar sem atualização geramos confusão desnecessária para o desenvolvedor.

Comentários de explicação são bons

Você pode não concordar com a solução do programador para o problema, mas, pelo menos, você sabe o que ele estava tentando fazer

//This is our best attempt to the job done
//by creating large number of options.
for (int i = 0; i < 25000; i++) {
   
}

Comentários com algum tipo de clarificação são bons

Em geral, é melhor encontrar uma maneira de tornar esse argumento ou valor de retorno claro por si só mas quando faz parte da biblioteca padrão, ou em código que você não pode alterar, um comentário esclarecedor útil pode ser útil.

Bom

assertTrue(a.compareTo(a) == 0); // a == a
assertTrue(a.compareTo(b) != 0); // a != b
assertTrue(ab.compareTo(ab) == 0); // ab == ab
assertTrue(a.compareTo(b) == -1); // a < b
assertTrue(aa.compareTo(ab) == -1); // aa < ab
assertTrue(ba.compareTo(bb) == -1); // ba < bb
assertTrue(b.compareTo(a) == 1); // b > a
assertTrue(ab.compareTo(aa) == 1); // ab > aa
assertTrue(bb.compareTo(ba) == 1); // bb > ba

Há um risco substancial, é claro, de que um comentário esclarecedor seja incorreto, então devemos sempre ter cuidado.

Aviso de consequências são bons

Às vezes, é útil avisar outros programadores sobre certas consequências de rodar um trecho de código ou realizar uma ação. Por exemplo, aqui está um comentário que explica por que um caso de teste específico está desativado

Bom

// Don't run unless you
// have some time to kill.
public void testWithReallyBigFile()
{}

Comentários TODO são bons

Às vezes, é razoável deixar notas “A fazer” na forma de comentários //TODO. No caso a seguir, o comentário TODO explica por que a função tem uma implementação degenerada e qual deve ser o futuro dessa função.

Bom

// TODO - We expect this to go away when we do the checkout model
protected VersionInfo makeVersion()
{
    return null;
}

Vale lembrar que //TODO não é desculpa para deixar o código ruim.

Comentários ruins

A maioria dos comentários se enquadra nesta categoria. Normalmente, eles são muletas ou desculpas para código ruim ou justificativas para decisões insuficientes, é considerado como se o programador estiver falando sozinho

Comentários que parecem resmungo são ruins

Colocar um comentário apenas porque você acha que deveria ou porque o processo exige que o faça é uma gambiarra. Se você decidir escrever um comentário, gaste o tempo necessário para ter certeza de que é o melhor comentário que você pode escrever.

Comentários redundantes são ruins

Comentários que dizem exatamente o que a função ou variável faz e recebe.

Ruim

// set DateTime now to the variable dateNow
var dateNow = DateTime.Now();

Comentários enganosos são ruins

Comentários que nos levam a acreditar que uma função retorna algo no exato momento em que realiza uma ação mas na verdade ela realiza uma série de validações antes da ação, são enganosos e devem ser evitados.

Comentários obrigatórios são ruins

É simplesmente bobo ter uma regra que diga que toda função deve ter um Doc, ou toda variável deve ter um comentário. Comentários como esse apenas confundem o código, propagam mentiras e geram confusão e desorganização geral.

Comentários tipo jornal são ruins

Às vezes, as pessoas adicionam um comentário no início de um módulo sempre que o editam.

Esses comentários se acumulam como uma espécie de diário, ou registro, de cada mudança que já foi feita. Além de poluir o modulo, são sempre ignorados. Controles de versão devem ser feitos pelas ferramentas desenvolvidas para este fim.

Comentários de ruído são ruins

Às vezes, você vê comentários que nada mais são do que ruído. Eles reafirmam o óbvio e não fornecem nenhuma informação nova.

Ruim

// The day of the month
private int dayOfMonth;

Esses comentários são tão barulhentos que aprendemos a ignorá-los. À medida que lemos o código, nossos olhos simplesmente os ignoram.

Outro problema é que eventualmente, os comentários começam a mentir conforme o código ao redor deles muda e estes ficam desatualizados.

Marcadores de posição são ruins

Ruim

// Actions //////////////////////////////////

Existem raras ocasiões em que faz sentido reunir certas funções sob um banner como este. Mas, em geral, eles são uma desordem que deve ser eliminada – especialmente a ruidosa sequência de barras no final.

Pense desta maneira. Um banner é surpreendente e óbvio se você não vê banners com muita frequência.

Comentários da chave de fechamento são ruins

Às vezes, os programadores farão comentários especiais sobre os colchetes de fechamento, como no exemplo abaixo.

Embora isso possa fazer sentido para funções longas com estruturas profundamente aninhadas, serve apenas para desorganizar o tipo de funções pequenas e encapsuladas que preferimos. Portanto, se você quiser marcar seus colchetes de fechamento, tente encurtar suas funções.

Ruim

while(condition){

    //Realy long code

}//while

Comentários de atribuições são ruins

Ruim

/* added by Developer */

Os sistemas de controle de código-fonte são muito bons em lembrar quem adicionou o quê e quando. Não há necessidade de poluir o código com estes comentários.

Códigos comentados são ruins

Poucas práticas são tão odiosas quanto comentar o código. Não faça isso!

Ruim

InputStreamResponse response = new InputStreamResponse();
response.setBody(formatter.getResultStream(), formatter.getByteCount());
// InputStream resultsStream = formatter.getResultStream();
// StreamReader reader = new StreamReader(resultsStream);
// response.setContent(reader.read(formatter.getByteCount()));

Houve um tempo, nos anos 60, em que comentar código poderia ser útil. Mas já temos bons sistemas de controle de código-fonte há muito tempo.

Esses sistemas vão lembrar o código para nós. Não temos que comentar mais. Apenas exclua o código. Não vamos perder. Confie no seu versionador.

Comentários HTML são ruins

HTML nos comentários do código-fonte é uma abominação. Isso torna os comentários difíceis de ler no único lugar onde deveriam ser fáceis de ler, no seu editor.

Se os comentários forem extraídos por alguma ferramenta para aparecer em uma página da Web, deve ser responsabilidade dessa ferramenta, e não do programador, adornar os comentários com o HTML apropriado.

Então não use tags como < p > < pre > & gt; etc

Comentários com informações originadas em outro local são ruins

Se você precisar escrever um comentário, certifique-se de que ele descreve o código ao qual aparece. Não ofereça informações de todo o sistema no contexto de um comentário local.

Considere, por exemplo, o comentário abaixo.

Ruim

/**
 * Port on which fitnesse would run. Defaults to <b>8082</b>.
 *
 * @param fitnessePort
 */
public void setFitnessePort(int fitnessePort)
{
    this.fitnessePort = fitnessePort;
}

Além do fato de ser terrivelmente redundante, também oferece informações sobre a porta padrão. E, no entanto, a função não tem absolutamente nenhum controle sobre o padrão.

O comentário não está descrevendo a função, mas alguma outra parte bem distante do sistema. É claro que não há garantia de que esse comentário será alterado quando o código que contém o padrão for alterado.

Comentários com muita informação são ruins

Não coloque discussões históricas interessantes ou descrições de detalhes irrelevantes em seus comentários.

Cabeçalhos de função são ruins

Funções curtas não precisam de muita descrição. Um nome bem escolhido para uma pequena função que faz uma coisa geralmente é melhor do que um cabeçalho de comentário.

Conclusão

Comentários devem ser usados sempre com o máximo de cuidado e o mínimo possível em seu código. O comentário é usado onde o código falha em mostrar. Um bom lembrete é, não use comentário quando você pode usar uma função ou variável.

Qualquer dúvida ou dicas, entre em contato: leandrolt@gmail.com

Referência
– Clean Code: A Handbook of Agile Software Craftsmanship (English Edition) – Robert C. Martin – Capítulo 4

Leave a Reply

Your email address will not be published. Required fields are marked *