Como estruturar comentários úteis no código
A maioria dos desenvolvedores escreve comentários que ninguém lê. Não é por malícia, é por preguiça ou falta de método. Quando você vê um bloco de código com uma linha dizendo "// inicializa variável", isso é ruído. O comentário não agrega informação nova porque o código já mostra isso claramente. O problema real começa quando o comentário tenta explicar o quê e esquece de explicar o porquê. Um exemplo de comentário funcional segue uma lógica simples: ele responde a perguntas que o leitor vai fazer ao tentar entender aquele trecho. Se o código faz algo óbvio, não comente. Se ele faz algo contraintuitivo, esse é o momento certo.
exemplo de comentário que funciona na prática
Veja a diferença entre dois estilos. O primeiro é o tipo que você vê em 90% dos repositórios: // Função de cálculo de impostos
function calcularImposto(base, alquota) { return base * alquota;
} Isso não é um comentário, é um rótulo. Qualquer um que saiba ler código entiende o que a função faz. Agora o segundo:
👉 Clique no botão abaixo para saber mais sobre o assunto!
// ISS estadual varia conforme o município de origem, não de destino. // Manter essa lógica separada evita duplicação na migração para o novo sistema tributário.
function calcularImposto(base, alquota) { return base * alquota;
} Aqui o comentário explica uma regra de negócio que o código por si só não comunica. Essa é a distinção que separa comentários úteis do resto.
Na minha experiência, o erro mais comum é subestimar o tempo que comentários desatualizados custam. Eu trabalhei num projeto onde a documentação dentro do código dizia que um parâmetro era obrigatório, mas a implementação tratava como opcional com fallback silencioso. Esse conflito durou quatro meses até alguém rastrear o bug até o comentário errado. A correção não foi consertar o código, foi atualizar o comentário para refletir o comportamento real e adicionar um log de aviso. Levei cerca de trinta minutos para resolver o que could ter levado dias a mais se o problema tivesse escalado. Outra coisa que pouca gente considera é a granularidade. Comentários em nível de linha funcionam apenas para trechos densos, como uma regex complexa ou uma transformação matemática não trivial. Para blocos maiores, prefira dividir a função em subfunções com nomes claros e comentar apenas as decisões arquiteturais. Um módulo de 200 linhas com dez comentários bem posicionados vale mais que 200 linhas com cinquenta comentários esparsos.
O limite prático é que comentários não substituem código legível. Se você precisa de um parágrafo inteiro para justificar uma função, o problema provavelmente está na assinatura ou na responsabilidade daquela função, não na falta de explicação. Comentários excessivos são frequentemente um sintoma de código problemático, não uma solução. Para projetos maiores, considere manter um arquivo de contribuição com exemplos padrão de comentário. Isso padroniza o que é esperado e reduz a carga cognitiva de quem entra no projeto. Um guia de estilo interno resolve mais do que discutir cada caso isoladamente no code review.
