Review and clean code comments
Table of Contents
When to use this skill
- When adding, editing, reviewing, or removing comments in code.
- After code changes, before committing.
- When the user asks to clean comments in a diff or across the repository.
How to use this skill
- Choose the scope. Default to diff-only cleanup: inspect the complete staged and unstaged patch and edit only the comments that patch introduces or changes. Use repository-wide cleanup only when the user explicitly asks for it; otherwise unchanged comments in a file are out of scope.
- Apply the comment rules from the comment
rules reference. In one line: comments are sparse, above the code,
never narrated as edit history, never end-of-line — except Doxygen
///<trailing comments, the codebase convention for documenting public API (see the code review checklist). - Remove comment clutter: commented-out code; comments that merely restate the code or the method name; edit-history narration.
- Preserve necessary comments: TODO, FIXME and similar work markers; linter, formatter, compiler, coverage, and generated-code directives; non-obvious reasoning, constraints, and business rules; pre-existing comments during diff-only cleanup.
- Focus only on comments. Do not change executable code, behavior, or formatting unrelated to the moved or removed comment. Regenerate generated files instead of editing them.
- Report the outcome with a before/after table (see examples). If the code already complies, say so — do not force changes onto compliant code.
Recipes
- How do I clean code comments? — the cleanup pass in full procedural detail.
Reference
- Comment rules reference — the canonical merged rule set, with the source of each rule.
- Before/after examples — worked examples built for this skill.
- comment-cleanup skill — by Craig Motlin (Apache-2.0); the scope, remove, preserve, and placement rules are adapted from it.
- clean-code-comments skill — on mcpmarket.com; the Comment Guidelines list is adapted from that page (transcribed by the ORE Studio user; the page declares no license).
- Code review checklist — the
Doxygen-on-public-API convention that defines the
///<exception.