Comment Guidelines

Core Principles

1. Self-documenting code first - Use clear naming and structure; comments are last resort
2. WHY over WHAT - Comments explain intent and reasoning, not mechanics
3. Reduce cognitive load - Make non-obvious knowledge explicit
4. Zero redundancy - Never duplicate what code already expresses

When to Add Comments

• Design decisions and trade-offs
• Non-obvious behavior or edge cases
• Interface contracts (public APIs, function signatures)
• Important context that isn't evident from code
• Gotchas and subtle behaviors
• Cross-module dependencies

• What the code literally does (self-evident)
• Well-named variables/functions
• Standard patterns and idioms
• Implementation details visible in code

Application Rules

1. Remove any comments that restate what code does
2. Keep comments that explain WHY something is done
3. Add comments only for non-obvious behavior or design decisions
4. Update existing comments if code changes make them stale
5. Never add comments just to fill space or appear thorough

Examples

// BAD: Restates the obvious
// Set user name to the input value
user.name = input.value;

// GOOD: Explains non-obvious behavior
// Normalize to lowercase for case-insensitive matching in search
user.searchKey = user.name.toLowerCase();

// BAD: Documents what is self-evident
// Loop through all items
for (const item of items) { ... }

// GOOD: Explains WHY this approach
// Process in reverse to allow safe removal during iteration
for (let i = items.length - 1; i >= 0; i--) { ... }

Automatic Application

• Apply these principles whenever editing code
• Proactively clean up redundant comments encountered
• Add strategic comments only where they reduce cognitive load