What is code-commenter?

This Claude skill enhances code maintainability and readability by generating high-quality, context-aware comments. Unlike basic tools that describe what code does, it focuses on the 'why,' documenting architectural decisions, performance trade-offs, and edge cases across major languages like Python, C++, Java, and JavaScript to improve long-term software quality.

When should I use code-commenter?

code-commenter is useful in the following scenarios: • Legacy Code Onboarding: Automatically add context and reasoning to undocumented legacy codebases to help new developers understand original design intents and constraints. • Complex Logic Documentation: Explain the reasoning behind non-obvious algorithms, performance optimizations, and memory management strategies in systems programming languages like Rust and C++. • Standardized Docstring Generation: Create consistent, professional documentation (e.g., Javadoc, PEP 257, or Doxygen) for functions, including parameters, side effects, and specific constraints. • Technical Debt Reduction: Improve code maintainability by highlighting 'gotchas,' hidden assumptions, and concurrency risks (like mutex requirements) to prevent future bugs.

name	code-commenter
description	Add detailed comments explaining WHY code works, its context, edge cases, and performance implications. Use when user mentions "add comments", "document", "explain code", "improve readability", or "maintainability". Supports C++, Python, Java, JavaScript, Go, Rust, SQL.

Code Commenter

Add high-quality comments that explain WHY code works, not just WHAT it does.

Core Principles

1. Explain WHY, not WHAT

Explain reasoning and business context, not just what the code does.

// Bad: Increment counter
counter++;

// Good: Track failed connection attempts for exponential backoff
counter++;

2. Document Non-Obvious Decisions

Explain performance trade-offs, algorithm choices, constraints.

// Use bloom filter for memory efficiency: 10x memory savings, false positives acceptable
// for duplicate detection. Hash set would be more accurate but needs 10x more RAM.

3. Highlight Edge Cases and Gotchas

// IMPORTANT: Don't call from within a transaction - opens its own tx, causing deadlock
// NOTE: This mutex must be held when accessing sharedCache (race condition otherwise)

4. Document Assumptions

// ASSUMES: Input already sanitized, max 1000 chars
// CONSTRAINT: Parser doesn't handle nested parens beyond depth 3

Comment Types

File/Module Level: Purpose, dependencies, constraints Function/Method: Purpose, parameters, side effects, performance notes Inline: Explain specific lines when non-obvious Section: Break long functions into logical sections TODO/FIXME: Track technical debt

See EXAMPLES.md for detailed examples of each type.

Language-Specific Guidelines

C/C++: Doxygen style, explain memory/thread safety Python: Docstrings (PEP 257), type hints, examples Java: JavaDoc, thread safety, exceptions
JavaScript/React: Props, state, performance notes Go: Exported symbols, concurrency, context Rust: Doc comments, ownership, lifetimes SQL: Join logic, performance, business rules

For detailed examples, see LANGUAGE_GUIDE.md.

What NOT to Comment

Don't state the obvious: x = 5; doesn't need a comment saying "set x to 5" Don't comment bad code - refactor it: Make code self-documenting with good names Don't maintain outdated comments: Delete rather than keep misleading comments

Output Format

Preserve original code structure (don't reformat unless requested)
Add comments naturally where they make logical sense
Match existing comment style in the codebase
After commenting, provide brief summary of what was documented

Example:

I've added comments to explain:
- Algorithm complexity and trade-offs
- Edge case handling for empty inputs  
- Memory management strategy
- Non-obvious performance optimizations

Best Practices

✅ DO:

Explain WHY and provide context
Document assumptions, constraints, edge cases
Use clear, concise language
Keep comments close to relevant code
Update comments when code changes

❌ DON'T:

State the obvious
Comment bad code instead of fixing it
Write novels - be concise
Leave outdated comments
Comment out code (use version control)

code-commenter

When & Why to Use This Skill

Use Cases