comment-cleanup
Guidelines for comments in code. Use when adding, editing, or removing comments.
When & Why to Use This Skill
This Claude skill streamlines the code documentation process by enforcing professional commenting standards. It focuses on improving code maintainability and readability by eliminating redundant information, removing dead code, and ensuring that comments provide meaningful context rather than describing version history or obvious logic.
Use Cases
- Refactoring legacy codebases: Identifying and removing obsolete 'commented-out' code blocks to reduce technical debt and clutter.
- Standardizing documentation style: Ensuring all team members follow best practices, such as placing comments above the code and avoiding end-of-line remarks.
- Enhancing code review efficiency: Automatically flagging comments that describe the process of change (e.g., 'added feature X') rather than the current state of the logic.
- Improving code readability: Stripping away unnecessary comments that state the obvious, allowing developers to focus on complex logic and architectural intent.
| name | comment-cleanup |
|---|---|
| description | Guidelines for comments in code. Use when adding, editing, or removing comments. |
Comment Guidelines
- Use comments sparingly
- Don't comment out code
- Remove it instead
- Don't add comments that describe the process of changing code
- Comments should not include past tense verbs like added, removed, or changed
- Example:
this.timeout(10_000); // Increase timeout for API calls - This is bad because a reader doesn't know what the timeout was increased from, and doesn't care about the old behavior
- Don't add comments that emphasize different versions of the code, like "this code now handles"
- Do not use end-of-line comments
- Place comments above the code they describe