0 Compartilhamentos 164 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 (03/07)
Notícias
9 visualizações
Notícias
9 visualizações

Promoções de Jogos do Final de Semana (03/07)

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

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

Como plugar um dispositivo USB corretamente… de primeira!
Dicas
11 visualizações
Dicas
11 visualizações

Como plugar um dispositivo USB corretamente… de primeira!

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

Impossível? Feitiçaria? A resposta estava bem diante de nossos olhos todo esse tempo...

Microsoft está mapeando o planeta inteiro para simulador de voo
Artigos
15 visualizações
Artigos
15 visualizações

Microsoft está mapeando o planeta inteiro para simulador de voo

Carlos L. A. da Silva - 1 de julho de 2020

A franquia Flight Simulator está prestes a renascer com um nível de realismo jamais alcançado antes.

Deixe um Comentário

Your email address will not be published.

Mais publicações

Promoções de Jogos do Final de Semana (26/06)
Notícias
18 visualizações
18 visualizações

Promoções de Jogos do Final de Semana (26/06)

Carlos L. A. da Silva - 26 de junho de 2020
Os 10 melhores plugins de formulário para WordPress em 2020
Artigos
20 visualizações
20 visualizações

Os 10 melhores plugins de formulário para WordPress em 2020

Carlos L. A. da Silva - 26 de junho de 2020
Você precisa conhecer Deno
Artigos
23 visualizações
23 visualizações

Você precisa conhecer Deno

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

Promoções de Jogos do Final de Semana (19/06)

Carlos L. A. da Silva - 19 de junho de 2020