Desde quando comecei a trabalhar com desenvolvimento de software, ouvia sempre uma frase que é muito repetida até hoje. A conhecida frase diz que: “Código bom é código comentado”.

Em conversas com outros desenvolvedores, alguns reclamavam porque que se viam obrigados a comentarem seus códigos para poderem passar pelas auditorias internas. Hoje vejo isso como um absurdo (para não dizer outra coisa).

Muitos comentários podem mesmo ser parâmetro para definir um bom código? Eu, particularmente, sou defensor de um código não comentado, ou com o mínimo de comentários possível. Muitos devem estar se perguntando agora: como assim, código não comentado? Esse cara está ficando louco? Mas não falem mal de mim ainda, vou explicar o meu ponto de vista.

Um código comentado quase sempre é sinal de código ruim. Se você sentiu a necessidade de comentar seu código é porque até você está percebendo que o mesmo não está expressivo e que todas as suas linhas não conseguem refletir o seu verdadeiro objetivo.

Acredito que certos códigos realmente são difíceis de serem expressivos, mesmo sendo refatorados. Podemos citar, por exemplo, o uso de bibliotecas de terceiros que às vezes não apresentam o funcionamento esperado e, nesses casos, somos obrigados a comentar determinados trechos, para facilitar a vida dos outros desenvolvedores que futuramente irão dar manutenção no código.

Um outro caso que também pode caber comentários é quando estamos desenvolvendo uma biblioteca para ser utilizada externamente. Nessa situação, os comentários “podem” auxiliar o uso da biblioteca. Mas ainda permaneço com o pensamento de que podemos sempre buscar alternativas para evitar os comentários.

Um código muito comentado pode trazer outro problema: a manutenção do próprio comentário. Sabemos da dificuldade que é em muitos casos dar manutenção em um código de produção, agora some a isso o esforço de atualização também do comentário.

Seu código deve ser expressivo

Para tentar demonstrar um código expressivo, imaginei um exemplo em que seja necessário implementar um método que aplique descontos nas mensalidades dos alunos do 5° período ou superior, e que tenham o coeficiente de rendimento maior ou igual a 7.

Código com necessidade de comentário

Abaixo apresento o método “AplicarDescontosMensalidades” refatorado, com um código mais expressivo:

Código refatorado sem a necessidade de comentário

Depois de refatorar o código do método “AplicarDescontoMensalidades”, percebe-se que ele está mais expressivo e que o seu objetivo se mostra mais claro para quem lê o código do método agora.

Meu objetivo aqui não é condenar totalmente os comentários no código-fonte, mas sim levantar a questão que mais importante que ter um código muito comentado é ter um código expressivo.

O código precisa ter capacidade de dizer a sua intenção tanto nos nomes dos métodos que o compõe, quanto nas suas linhas. Ao sentir a necessidade de fazer um comentário, pare e reflita sobre a sua real necessidade, faça sempre as perguntas: por que tem que ter esse comentário? O código fica claro sem o comentário? Outros desenvolvedores irão entender mesmo esse código? E, se possível, procure sempre mostrar seu código para outros desenvolvedores da equipe e receber feedbacks sobre ele.

Robert C. Martin (Uncle Bob) cita no seu livro Código Limpo “Habilidades Práticas do Agile Software”, uma frase que diz muito sobre o pensamento que tenho:

“O único comentário verdadeiramente bom é aquele em que você encontrou uma forma para não escrevê-lo”.

Espero que tenha conseguido passar o recado e que agora vocês analisem bem a real necessidade dos comentários nos seus códigos. Para qualquer feedback, deixe seu comentário e participe dessa discussão. Até a próxima!