0 Compartilhamentos 921 Views

Como comentar seu código como um profissional

27 de dezembro de 2019

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.

Carregando...

Você pode se interessar

Sir Clive Sinclair, o homem adiantado no tempo
Artigos
68 visualizações
Artigos
68 visualizações

Sir Clive Sinclair, o homem adiantado no tempo

Carlos L. A. da Silva - 18 de setembro de 2021

O inglês Clive Marles Sinclair nasceu de uma família de engenheiros. Seu avô foi engenheiro, assim como o seu pai. Com um talento natural pela Matemática e um forte interesse em eletrônica, ele se tornaria uma página importante da popularização da computação em diversas partes do mundo, construindo um legado que se perpetuará por anos […]

A cibersegurança por trás das vacinas
Artigos
182 visualizações
Artigos
182 visualizações

A cibersegurança por trás das vacinas

Carlos L. A. da Silva - 7 de setembro de 2021

Vacinas contra o coronavírus contam com aparato sofisticado de cibersegurança que bateu de frente com tentativa de ação de hackers.

Top 25 comandos do Git
Artigos
319 visualizações
Artigos
319 visualizações

Top 25 comandos do Git

Carlos L. A. da Silva - 28 de agosto de 2021

Git é uma mão na roda para source control, mas pode ficar melhor ainda conhecendo os comandos certos.

Deixe um Comentário

Your email address will not be published.

Mais publicações

Dez anos de Kotlin: origens e futuro
Artigos
376 visualizações
376 visualizações

Dez anos de Kotlin: origens e futuro

Carlos L. A. da Silva - 20 de agosto de 2021
10 jogos que todo programador deveria conhecer
Artigos
691 visualizações
691 visualizações

10 jogos que todo programador deveria conhecer

Carlos L. A. da Silva - 1 de agosto de 2021