Comment Guidelines

These guidelines should be automatically applied whenever writing or modifying code.

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

DO comment:

• 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

DON’T comment:

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

Application Rules

When modifying code:

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

This skill does NOT need to be explicitly invoked. Claude should:

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