0 Compartilhamentos 102 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.

Você pode se interessar

Como remover sugestões de URL da barra de endereços do Chrome
Dicas
4 visualizações
Dicas
4 visualizações

Como remover sugestões de URL da barra de endereços do Chrome

Carlos L. A. da Silva - 9 de abril de 2020

Navegador guarda qualquer endereço visitado e sugere pra você, mas você não precisa apagar o Histórico inteiro para se livrar de um deles.

IBM amplia Call for Code Challenge 2020 para enfrentar o COVID-19
Notícias
8 visualizações
Notícias
8 visualizações

IBM amplia Call for Code Challenge 2020 para enfrentar o COVID-19

Redação - 7 de abril de 2020

A IBM está expandindo o desafio global Call For Code 2020 para abordar a reação do mundo com o COVID–19, além das mudanças climáticas: duas questões urgentes que podem comprometer nossa saúde, nosso planeta e nossa sobrevivência.

Que fim levou o Windows Phone?
Artigos
9 visualizações
Artigos
9 visualizações

Que fim levou o Windows Phone?

Carlos L. A. da Silva - 6 de abril de 2020

A longa história de estratégias equivocadas da Microsoft em dispositivos móveis e o fim de um sonho.

Deixe um Comentário

Your email address will not be published.

Mais publicações

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

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

Carlos L. A. da Silva - 3 de abril de 2020
Como descobrir se tem um “fantasma” no seu teclado
Dicas
20 visualizações
20 visualizações

Como descobrir se tem um “fantasma” no seu teclado

Carlos L. A. da Silva - 2 de abril de 2020
Trabalhando de casa
Artigos
30 visualizações
30 visualizações

Trabalhando de casa

Carlos L. A. da Silva - 30 de março de 2020
Promoções de Jogos do Final de Semana (27/03)
Notícias
29 visualizações
29 visualizações

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

Carlos L. A. da Silva - 27 de março de 2020