Regra

Comentário sobre o objetivo (porquê), não a mecânica (o quê).
Comentários que simplesmente reafirmam o que o código faz 
fornece não valor valor e pode tornar-se obsoleto.

Idiomas suportados: 45+

Introdução

Comentários que apenas repetem o que o código faz não fornecem clareza adicional e frequentemente ficam dessincronizados com a implementação. Quando os comentários divergem do código, eles introduzem confusão e atrasam as revisões. Comentários úteis explicam a intenção, suposições e o raciocínio por trás das decisões. Isso torna a lógica complexa mais fácil de entender e manter.

Por que isso importa

Implicações de segurança: Comentários baseados em intenção expõem suposições sobre validação, confiança na entrada ou controle de acesso que podem não ser visíveis na implementação.

Impacto no desempenho: Comentários que esclarecem decisões relacionadas ao desempenho ajudam a evitar otimizações acidentais ou mudanças que quebrem as características de desempenho esperadas.

Manutenibilidade do código: Comentários focados na intenção ajudam os desenvolvedores a entender por que uma parte do código existe, reduzindo o tempo necessário para modificá-lo ou auditá-lo.

Superfície de ataque: Comentários claros reduzem a chance de uso indevido de funções internas de maneiras que introduzem comportamento inseguro ou expandem a superfície de ataque.

Exemplos de código

❌ Não-conforme:

// Loop through users
for (const user of users) {
    // Convert email to lowercase
    user.email = user.email.toLowerCase();
}

Por que está errado: Esses comentários repetem o que o código já mostra, não fornecendo contexto sobre a intenção ou as restrições.

✅ Compatível:

/**
 * Normalize user emails so downstream permission checks
 * compare consistent lowercase values. Required because
 * external systems may send mixed-case emails.
 */
for (const user of users) {
    user.email = user.email.toLowerCase();
}

Por que isso importa: O comentário explica por que a normalização é necessária, esclarecendo a intenção e prevenindo refatorações incorretas.

Conclusão

Escreva comentários que expliquem por que o código é necessário, e não o que cada linha já mostra. Descreva suposições, restrições e o raciocínio quando não forem óbvios pela implementação. Isso cria uma documentação sustentável que permanece útil mesmo quando o código evolui.