ring:cleaning-comments

Cleaning Comments

When to use

• Code has excessive, redundant, or obvious comments
• During code review or post-refactor cleanup
• Before committing to clean up comment noise in changed files
• Codebase has accumulated commented-out code blocks

Skip when

• Reviewing documentation files (README, docs/, etc.)
• Comments are already minimal and meaningful
• Working with generated code or third-party files

Sequence

Runs after: ring:exploring-codebases (optional, for architecture context)

Related

Complementary: ring:exploring-codebases — run first for architecture-aware cleaning that preserves critical documentation

---

Analyze comments in code and remove those that violate clean code principles while preserving valuable ones. You can focus on git changes for faster, more relevant cleaning, or analyze the entire codebase.

Recommended workflow: Run ring:exploring-codebases first to understand the architecture, then clean comments with that context. This preserves architectural documentation, understands which comments are critical for complex modules, and respects project-specific documentation standards.

Clean Code Comment Rules

1. Always try to explain yourself in code — Remove comments that can be replaced with better function/variable names
2. Don't be redundant — Remove comments that just repeat what the code obviously does
3. Don't add obvious noise — Remove comments like i++; // increment i
4. Don't use closing brace comments — Remove } // end of if block style comments
5. Don't comment out code — Remove commented-out code blocks
6. Keep explanation of intent — Preserve comments explaining WHY, not WHAT
7. Keep warnings of consequences — Preserve comments about important side effects
8. Keep legal and informative comments — Preserve copyright, licenses, TODOs

Examples

Before:

// Check if user is eligible for discount
if (user.age >= 65 && user.membershipYears >= 5) {
  // Apply senior discount
  total = total * 0.9 // multiply by 0.9 to get 10% discount
} // end if block