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