Guia para escrever bons comentários de código

• Papel dos comentários de código:

  • Os comentários de código vão além de explicar “o que o código escrito faz” e também documentam decisões de design, trade-offs e outros pontos considerados
  • Com isso, explicam “o que o autor do código fez e por que fez dessa forma”
  • Os comentários de código ajudam a compartilhar o contexto das decisões tomadas durante o processo de escrita no passado
  • Isso transmite informações sobre o código que são difíceis de expressar apenas com o próprio código

• Importância dos comentários de código:

  • Comentários inline colocados antes de código complexo economizam o tempo de outros desenvolvedores que verão esse código mais tarde
  • À medida que o projeto evolui, deixar registrado o contexto de decisões de código tomadas no passado ajuda outros desenvolvedores.
  • Se o código for complexo, deve haver ao menos um comentário inline de uma linha antes dele
  • Há limites para transmitir apenas com o código diversos tipos de informação, incluindo o contexto das decisões tomadas

• Como escrever bons comentários de código:

  1. Escreva de forma concisa
     • Escreva comentários apenas quando realmente necessário, incluindo somente as informações essenciais
       • Quando o código inevitavelmente for complexo
       • Ao adicionar detalhes para aumentar a precisão
       • Quando faltar contexto (ex.: ao usar código de outro repositório ou pacote)
     • Reduza confusão e ambiguidade nos comentários e forneça contexto e informações úteis
  2. Use comentários TODOs/FIXMEs
     • Comentários TODOs/FIXMEs são uma forma de indicar que “uma parte específica do código ainda não foi concluída ou precisa ser corrigida”
     • Escreva algo como “TODO: é preciso adicionar a funcionalidade XX” antes da função
     • Ao escrever código, quando pensar “preciso revisar esta parte depois” ou “essa funcionalidade deverá ser desenvolvida mais tarde”, usar esse método permite registrar e acompanhar os itens relacionados
     • Extension recomendada: TODO Highlight
  3. Não use comentários para justificar código
     • Em vez de se justificar com comentários em um código errado e pouco claro, reescreva o código
     • Alguns códigos precisam ser explicados com comentários, mas outros devem falar por si mesmos, sem depender deles
  4. Use IA
     • Ao usar um gerador de comentários com IA, é possível criar comentários em um formato consistente de acordo com determinados padrões
     • Isso ajuda a manter a consistência dos comentários em todo o projeto, melhorando a legibilidade do código
     • Gerador de comentários com IA recomendado: Readable

[penza1]

Se parece que um comentário é necessário,
talvez valha a pena refletir se o código não está errado.

Comentários que não acompanham o código em sua vida e funcionalidade podem acabar gerando confusão para o desenvolvedor que os verá no futuro, ou até para nós mesmos.

Mesmo quando o contexto do passado já não tem relação com o presente ou até causou erros,
aquela frase do contexto antigo pode nos fazer hesitar em corrigir o estado atual, ou nos levar a contornar o problema tentando resolvê-lo com outra estrutura,
e isso pode até provocar mais erros...

Pela minha experiência, não são tantos os comentários que realmente ajudam a entender por que algo estava certo naquela época, mas está errado agora....

[ironlung]

Obrigado por compartilhar uma opinião tão valiosa. Pensando no que você compartilhou, sinto que, para a evolução do código, também é necessário fazer o esforço de questionar com cuidado a real necessidade dos comentários. :)

[aqqnucs]

https://youtu.be/Bf7vDBBOBUA?si=0-v44x48-rlVsYCq

Enquanto vejo isso, também tento não exagerar no uso de comentários

[ironlung]

Obrigado por compartilhar um ótimo vídeo! :)

[iamchanii]

Por melhor que uma estrada esteja pavimentada, acho que as placas de sinalização continuam sendo indispensáveis. Por isso, ultimamente tenho tentado criar o hábito de escrever comentários.

[ironlung]

Obrigado por compartilhar seus insights nos comentários. Pensando no que você disse, percebo novamente que comentários também são uma forma importante de escrita técnica, o que me faz revisitar os princípios básicos da escrita. :)

[balak]

Acho que o ideal é escrever o código de forma que ele seja compreensível mesmo sem comentários.

[ironlung]

Sim, acho que o mais importante é se manter fiel ao básico primeiro. Obrigado pelo comentário. :)