Regra 

Funções sem comentários explicativos.
Funções sem comentários são difíceis de 
entender para outros desenvolvedores.

Linguagens suportadas: 45+

Introdução

Funções sem comentários forçam os desenvolvedores a inferir a intenção apenas a partir dos detalhes de implementação. Isso retarda as revisões de código e torna a manutenção mais propensa a erros. Explicações ausentes também ocultam suposições sobre validação, expectativas de entrada ou restrições de segurança. Documentação clara reduz o uso indevido e ajuda as equipes a entender o comportamento do código mais rapidamente.

Por que isso importa

Implicações de segurança: Comentários ausentes ocultam suposições sobre validação, verificações de autorização e entradas confiáveis, tornando o uso indevido mais fácil e aumentando os riscos de segurança.

Impacto no desempenho: Funções não documentadas podem ser usadas incorretamente, causando operações caras repetidas, parsing desnecessário ou manipulação ineficiente de dados.

Manutenibilidade: Desenvolvedores gastam mais tempo lendo e fazendo engenharia reversa da lógica quando a intenção não está documentada, atrasando o refactoring e o onboarding.

Exemplos de código

❌ Não-conforme:

// No explanation of expected input or security assumptions
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Por que está errado: A função processa campos relevantes para a segurança, mas não documenta premissas sobre fontes confiáveis, estrutura esperada ou restrições de entrada.

✅ Compatível:

/**
 * Normalize user data from external input.
 * Expects: `user` contains `id`, `email`, and `roles`.
 * Rejects invalid structures and filters unsafe role values.
 * Ensures normalized identifiers and lowercased email for consistency.
 */
function normalizeUser(user) {
    if (!user || typeof user !== 'object') return null;

    return {
        id: String(user.id).trim(),
        email: user.email.toLowerCase(),
        roles: user.roles.filter(r => r !== 'guest')
    };
}

Por que isso importa: O comentário documenta a intenção, as entradas esperadas e as restrições de segurança, tornando o uso previsível e prevenindo integrações inseguras.

Conclusão

Adicione comentários claros a qualquer função onde a intenção, suposições ou restrições não são óbvias pela assinatura. Documente o que a função espera, o que ela retorna e qualquer comportamento relevante para a segurança. Isso melhora a qualidade da revisão, reduz o uso indevido e garante um comportamento previsível em toda a base de código.