0 Compartilhamentos 287 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

Promoções de Jogos do Final de Semana (04/12)
Notícias
10 visualizações
Notícias
10 visualizações

Promoções de Jogos do Final de Semana (04/12)

Carlos L. A. da Silva - 4 de dezembro de 2020

Confira as melhores ofertas de jogos de PC para o final de semana.

E o que dizer do 6G? E o 7G?
Artigos
7 visualizações
Artigos
7 visualizações

E o que dizer do 6G? E o 7G?

Carlos L. A. da Silva - 3 de dezembro de 2020

China sai na frente com desenvolvimento da tecnologia da rede 6G, mas analistas estão divididos sobre um "7G".

Perguntas e respostas sobre o 5G
Artigos
11 visualizações
Artigos
11 visualizações

Perguntas e respostas sobre o 5G

Carlos L. A. da Silva - 30 de novembro de 2020

Tecnologia já está batendo na nossa porta, mas muitas pessoas não entendem completamente como ela funciona e o que vai mudar no dia a dia.

Deixe um Comentário

Your email address will not be published.

Mais publicações

Como usar a internet de forma segura com os novos DNS da Cloudflare
Dicas
14 visualizações
14 visualizações

Como usar a internet de forma segura com os novos DNS da Cloudflare

Carlos L. A. da Silva - 28 de novembro de 2020
Como a Nvidia está usando rede neural no lugar de codecs de vídeo
Artigos
20 visualizações
20 visualizações

Como a Nvidia está usando rede neural no lugar de codecs de vídeo

Carlos L. A. da Silva - 25 de novembro de 2020
Promoções de Jogos do Final de Semana (20/11)
Notícias
24 visualizações
24 visualizações

Promoções de Jogos do Final de Semana (20/11)

Carlos L. A. da Silva - 20 de novembro de 2020