Código legível reduz necessidade de comentário, mas não elimina contexto. Existem decisões que não aparecem na sintaxe: uma regra de negócio estranha, uma limitação de integração, uma escolha de desempenho ou um cuidado de compatibilidade.
Comentário bom explica por que algo existe. Comentário fraco descreve o que a linha seguinte já mostra. A diferença aparece meses depois, quando outra pessoa precisa alterar sem conhecer a conversa original.
Onde comentar
Comente limites, invariantes e exceções. Se uma validação protege uma integração antiga, diga isso. Se um cálculo segue contrato externo, registre o contrato. Se uma solução evita comportamento específico de biblioteca, deixe a pista.
Também vale documentar pontos de extensão. Uma função usada por jobs, API e importador não deve parecer local. O comentário curto pode evitar mudança aparentemente inocente que quebra outro fluxo.
Onde não comentar
Não use comentário para compensar nome ruim, função gigante ou fluxo confuso. Antes de escrever um parágrafo explicando uma condição, tente melhorar nomes, extrair etapas ou reorganizar o código.
Comentários operacionais também precisam sair quando o código muda. Uma explicação antiga e errada é pior do que silêncio, porque cria confiança em informação falsa.
Um exemplo de comentário que muda a manutenção
Imagine um importador que recebe o campo ativo=0 para um cadastro ainda válido porque um parceiro usa zero como estado inicial, não como exclusão. Um comentário útil junto da conversão explicaria o contrato, apontaria a versão da integração e diria qual teste protege esse caso. Sem esse contexto, alguém pode “corrigir” a condição e rejeitar registros legítimos. Já comentar que ativo recebe o valor convertido apenas repete o código.
Ao mudar o contrato do parceiro, revise comentário, teste e documentação na mesma alteração. Se a explicação exige vários parágrafos ou envolve decisão entre equipes, registre-a também em documento de arquitetura e deixe no código uma referência curta. A pergunta para revisão é simples: retirar este comentário faria alguém tomar uma decisão errada?
Documente perto da decisão
A documentação mais útil costuma ficar perto do ponto que ela explica. Arquitetura geral pode morar fora do código, mas detalhes de comportamento crítico devem acompanhar a implementação que depende deles.
