Rule

Comment on the goal (why), not the mechanics (what).
Comments that simply restate what the code does 
provide no additional value and can become outdated.

Supported languages: 45+

Introduction

Comments that restate what the code does provide no additional clarity and often fall out of sync with the implementation. When comments diverge from the code, they introduce confusion and slow down reviews. Useful comments explain intent, assumptions, and reasoning behind decisions. This makes complex logic easier to understand and maintain.

Why it matters

Security implications: Intent based comments expose assumptions around validation, input trust, or access control that might not be visible in the implementation.

Performance impact: Comments that clarify performance related decisions help avoid accidental optimizations or changes that break expected performance characteristics.

Code maintainability: Intent focused comments help developers understand why a piece of code exists, reducing the time needed to modify or audit it.

Attack surface: Clear comments reduce the chance of misusing internal functions in ways that introduce unsafe behavior or expand the attack surface.

Code examples

❌ Non-compliant:

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

Why it’s wrong: These comments repeat what the code already shows, providing no context about intent or constraints.

✅ Compliant:

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

Why this matters: The comment explains why normalization is required, clarifying intent and preventing incorrect refactoring.

Conclusion

Write comments that explain why the code is necessary, not what each line already shows. Describe assumptions, constraints, and reasoning when they are not obvious from the implementation. This creates maintainable documentation that remains useful even when the code evolves.