Rule 

Functions without explanatory comments.
Functions without comments are hard to 
understand for other developers.

Supported languages: 45+

Introduction

Functions without comments force developers to infer intent from implementation details alone. This slows down code reviews and makes maintenance more error prone. Missing explanations also hide assumptions around validation, input expectations, or security constraints. Clear documentation reduces misuse and helps teams understand code behavior faster.

Why it matters

Security implications: Missing comments hide assumptions around validation, authorization checks, and trusted inputs, making misuse easier and increasing security risks.

Performance impact: Undocumented functions may be used incorrectly, causing repeated expensive operations, unnecessary parsing, or inefficient data handling.

Maintainability: Developers spend more time reading and reverse engineering logic when intent is not documented, slowing down refactoring and onboarding.

Code examples

❌ Non-compliant:

// 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')
    };
}

Why it’s wrong: The function processes security relevant fields but does not document assumptions about trusted sources, expected structure, or input constraints.

✅ Compliant:

/**
 * 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')
    };
}

Why this matters: The comment documents intent, expected inputs, and security constraints, making usage predictable and preventing unsafe integration.

Conclusion

Add clear comments to any function where intent, assumptions, or constraints are not obvious from the signature. Document what the function expects, what it returns, and any security relevant behavior. This improves review quality, reduces misuse, and ensures predictable behavior across the codebase.