About clean-comments
clean-comments is a coding skill for developers who want comments to clarify code rather than duplicate it. It gives concise rules for removing stale or commented-out code and writing useful technical notes.
Key features
- 01Remove metadata from comments
- 02Delete obsolete comments
- 03Avoid comments that repeat code
- 04Write brief, clear technical notes
- 05Remove commented-out code
Use cases
- 01Review comments during code cleanup
- 02Replace explanations of what code does with why
- 03Remove stale notes after code changes
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/clean-commentsin Claude Code to confirm it loaded.
Details
From the project READMEClean Comments
C1: No Inappropriate Information
Comments shouldn't hold metadata. Use Git for author names, change history, ticket numbers, and dates. Comments are for technical notes about code only.
C2: Delete Obsolete Comments
If a comment describes code that no longer exists or works differently, delete it immediately. Stale comments become "floating islands of irrelevance and misdirection."
C3: No Redundant Comments
// Bad - the code already says this
i += 1; // increment i
user.save(); // save the user
// Good - explains WHY, not WHAT
i += 1; // compensate for zero-indexing in display
C4: Write Comments Well
If a comment is worth writing, write it well:
- Choose words carefully
- Use correct grammar
- Don't ramble or state the obvious
- Be brief
C5: Never Commit Commented-Out Code
// DELETE THIS - it's an abomination
// function oldCalculateTax(income: number): number {
// return income * 0.15;
// }
Who knows how old it is? Who knows if it's meaningful? Delete it. Git remembers everything.
The Goal
The best comment is the code itself. If you need a comment to explain what code does, refactor first, comment last.