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

Como se tornar um Engenheiro DevOps em 2021
Notícias
7 visualizações
Notícias
7 visualizações

Como se tornar um Engenheiro DevOps em 2021

Carlos L. A. da Silva - 1 de março de 2021

A consultora de DevOps e evangelista Nana Janashia apresenta um passo a passo de tudo que você precisa saber para dominar o DevOps em 2021.

Quanto ganha um programador? Confira uma das maiores pesquisas salariais realizadas no Brasil
Notícias
10 visualizações
Notícias
10 visualizações

Quanto ganha um programador? Confira uma das maiores pesquisas salariais realizadas no Brasil

Redação - 23 de fevereiro de 2021

O Canal Código Fonte TV realizou uma pesquisa salarial com mais de 11 mil programadores brasileiros. Entre os dados coletados é possível analisar a média salarial por: tecnologia, idade, gênero, região, entre muitos outros insights.

Seus dados vazaram. E agora?
Artigos
13 visualizações
Artigos
13 visualizações

Seus dados vazaram. E agora?

Carlos L. A. da Silva - 19 de fevereiro de 2021

Seus dados pessoais foram vazados e essa é uma verdade praticamente inevitável. A meta agora é minimizar os possíveis danos e cobrar autoridades.

Deixe um Comentário

Your email address will not be published.

Mais publicações

Entendendo o elemento time em HTML 5
Artigos
19 visualizações
19 visualizações

Entendendo o elemento time em HTML 5

Carlos L. A. da Silva - 5 de fevereiro de 2021
Como cortar texto sem usar uma linha de script
Dicas
26 visualizações
26 visualizações

Como cortar texto sem usar uma linha de script

Carlos L. A. da Silva - 11 de janeiro de 2021
Como começar a programar
Artigos
32 visualizações
32 visualizações

Como começar a programar

Carlos L. A. da Silva - 7 de janeiro de 2021
Como cancelar qualquer conta online para sempre
Dicas
33 visualizações
33 visualizações

Como cancelar qualquer conta online para sempre

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