Você foi chamado emergencialmente para resolver um problema em uma aplicação crítica que parou de funcionar. É noite de Natal, todo mundo está comemorando e você está analisando um código fonte que é mais antigo que o guaraná de rolha. São milhares de linhas de código, com inúmeros componentes, bibliotecas, dependências, heranças… e seja lá quem for que escreveu isso não deixou uma única linha de comentário. Documentação? Foi comida pelas traças ou nunca existiu.
Para que você não estrague o Natal de alguém em um futuro distante ou próximo, é fundamental comentar seu código. Esse alguém pode inclusive ser você. Com a mente fresca, envolvimento pleno com um projeto, é fácil entender o que foi feito e como funciona a aplicação, o sistema. Em um mês alocado em outra tarefa, em outra linguagem, os detalhes começam a ficar escassos, as soluções não parecem mais tão óbvias como antes. Seis meses depois, você não reconhece mais seu próprio código.
Existem programadores que são avessos a comentários, porque acreditam cegamente que um código bem estruturado dispensa comentários, que o comentário seria um indicativo de que algo não está claro, que os nomes adotados, a lógica ou alguma outra coisa está incompleta. Na verdade, comentar no código não é desculpa para um código mal-feito, mas até o mais perfeito dos códigos precisa de esclarecimentos, de redundância até, para eliminar todo o risco de ambiguidade e confusão e agilizar os trabalhos.
É claro que a sintaxe para deixar comentários varia para cada linguagem de programação, mas os princípios de um bom comentário se mantém: brevidade, relevância e contexto. Dito isso, use e abuse dos comentários, para não se arrepender depois ou não fazer outra pessoa se arrepender de rever seu código.
Nossa primeira dica é tentar evitar o famoso “blocão de comentário” no início do código. É estranho recomendar escrever comentários e imediatamente depois recomendar não escrever? Não necessariamente. O blocão no header mais atrapalha do que ajuda, já que contém material que deveria estar presente na documentação do projeto e não no próprio código. É preciso saber separar o conteúdo, sob o risco de dificultar a manutenção do projeto.
Desta forma, o cabeçalho do código deve ser melhor empregado para informações básicas, como versão da aplicação, versões das bibliotecas e a data da última alteração.
Dentro do código, ou inline, como dizem alguns, é recomendável descrever funções de forma sucinta e variáveis importantes, sem exageros. Não há qualquer tipo de regra para o que é excessivo ou redundante e apenas a prática poderá indicar o que deve ou não ser comentado. Se serve de parâmetro, busque escrever o tipo de informação que você gostaria de ler no código que você dá manutenção. Em termos gerais, o que um código faz deveria ser óbvio mas o porquê nem sempre é tão claro, precisando ser comentado.
Se você deseja manter o profissionalismo, nunca, jamais, escreva comentários depreciativos de qualquer tipo, seja contra o projeto, um colega de trabalho ou a empresa. Rancores passam, o comentário vai ficar ali para sempre ou até algum programador mais responsável ler aquilo e remover. Não finja que nunca fez isso ou pelo menos sentiu vontade de fazer…
Entretanto, alguns tópicos são indispensáveis. Entre eles, estão os alertas, os avisos de que há um problema à frente no código e foi encontrada uma solução provisória. Em inglês, isso seria o workaround, mas no bom e velho vocabulário do desenvolvedor brasileiro, estamos falando da “gambiarra”. Nem sempre a solução mais elegante ou mais correta do ponto de vista da sintaxe ou a melhor prática recomendada nos manuais é a solução que efetivamente resolve um problema e isso deve ficar explícito através de um comentário.
Nesses casos, é bom relatar o problema encontrado, como isso afeta outras partes do sistema ou aplicação, por que motivo tal saída foi adotada e como a saída supostamente mais óbvia não é recomendada. Esse é o tipo de comentário que pode salvar horas ou dias de desenvolvimento de alguém no futuro.
Se achar necessário, comente a porção do código que não funcionou e deixe como um legado, para registrar que aquela abordagem não deu certo.
