Improves code comments so they are clear, accurate, and useful. Use when asked to "clean up the comments", "improve the comments", or "document this function".
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Is that skill safe to install?
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
Are you the author of Tidy Comments?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/mblode-tidy-comments)
---
name: tidy-comments
description: Improves code comments so they are clear, accurate, and useful. Use when asked to "clean up the comments", "improve the comments", or "document this function".
---
# Tidy Comments
Good comments make code easier to understand. This skill helps you write better ones.
## Principles
- Comments should explain why, not what. The code already says what it does.
- Keep comments short and to the point.
- Make sure comments are accurate. An outdated comment is worse than no comment.
- Use complete sentences with correct spelling and grammar.
- Do not state the obvious. `i++ // increment i` adds nothing.
- Remove commented-out code. Version control remembers it.
- Write a doc comment for every public function, describing its parameters and return value.
## Steps
1. Read the file carefully and understand what it does.
2. Think step by step about which comments are helpful and which are not.
3. Remove comments that restate the code.
4. Rewrite unclear comments so they are clear.
5. Add comments where the reasoning is not obvious.
6. Double-check your work before finishing.
## Tips
- Imagine a new teammate reading the code for the first time.
- When in doubt, prefer a better name over a comment.
- Be careful and thorough. Take your time.
