Comentário bom é comentário apagado

Quando o assunto é comentário de código, eu concordo com o Juan Lopes:

maçãs verdes com rótulo de

Acho que comentários ficam desatualizados com uma facilidade incrível. É como se eles começassem a apodrecer assim que são escritos. Geralmente quando pensamos em incluir um comentário é porque o código está difícil de entender. Sentimos que está difícil de nos expressar com código e trocamos de linguagem. Nós acabamos cedendo e passamos de uma mídia de comunicação (o código) para outra (a linguagem natural).

Sim. O código é uma mídia de comunicação.

E não estou falando de comunicação com o computador. Estou falando de comunicação com seus colegas programadores. Se o código está difícil de entender, não escreva uma comentário, re-estruture o código! O que não faz sentido é você passar de uma linguagem deliberadamente projetada para eliminar ambiguidades para uma linguagem onde termos diferentes podem ter significados diferentes para pessoas diferentes.

Tendo dito isto, existe sim uma classe de comentários que acho extremamente útil e que venho utilizando cada vez mais.

São os comentários de tarefas pendentes.

Às vezes você está no meio de uma alteração e se depara com um pedaço de código pré-existente que poderia ser melhorado. Ou você sabe que o magic number que está usando deveria ser configurável. Ou então você toma uma atalho qualquer para validar a solução que está desenvolvendo com seu commit pequeno da vez, mas sabe que aquilo não pode ficar daquele jeito quando a funcionalidade estiver pronta.

Enfim, você identificou algo no código que ainda precisa ser trabalhado, mas não é algo diretamente ligado à modificação imediatamente atual. É aí que entram os comentários. Você os usa como lembretes de algo que ainda precisa ser feito, mas se desimpede para se concentrar em uma coisa de cada vez.

Os meus eu, inspirado em alguma tradição de programação milenar cuja origem desconheço, gosto de separar em duas classes: TODO e FIXME.

Os comentários TODO são usados quando quero assinalar algo que pode ser melhorado, mas que não impede o funcionamento correto da aplicação. Pode ir desde uma referência hard-coded a um webservice a uma idéia arquitetural para implementação de uma funcionalidade futura, dependendo do caso.

A palavra em ênfase aqui é “correto”.

É aí que entram os comentários FIXME. Esses eu uso quando preciso marcar algo em que não vou tocar agora, mas que considero que deva estar pronto para que a tarefa atual possa ser dada como concluída. Se os FIXME não forem consertados, a aplicação não funciona corretamente.

No fim das contas o ideal é não ter nenhum desses comentários “sujando” meu código-fonte. Mesmo que os TODO possam ser mantidos indefinidamente dentro da aplicação, o objetivo de vida deles, desde o momento em que nascem, é desaparecer. Nesse sentido, todos os comentários devem ser considerados temporários.

O que você não deve ter de jeito nenhum dentro do seu código são comentários assim:

# soma um com dois, dando como resultado três
r = 1 + 2

Isto é diretamente equivalente à figura das maçãs do início do texto. É um desastre esperando para acontecer!

2 thoughts on “Comentário bom é comentário apagado

  1. Oi Thiago,

    Excelente post! Concordo com você em todos os pontos. Contudo, aceito que comentários podem ser úteis em trechos de códigos complexos onde a linguagem ou mesmo o algoritimo implementado não ajuda muito o entendimento, por mais que você refatore e melhore o código. Enfim é uma exceção a regra.

    Um abraço!

Comments are closed.