Comment Guidelines
These guidelines should be automatically applied whenever writing or modifying code.
Core Principles
- Self-documenting code first - Use clear naming and structure; comments are last resort
- WHY over WHAT - Comments explain intent and reasoning, not mechanics
- Reduce cognitive load - Make non-obvious knowledge explicit
- 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:
- Remove any comments that restate what code does
- Keep comments that explain WHY something is done
- Add comments only for non-obvious behavior or design decisions
- Update existing comments if code changes make them stale
- 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