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

  1. 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.
  2. 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).
  3. Remove comment clutter: commented-out code; comments that merely restate the code or the method name; edit-history narration.
  4. 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.
  5. 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.
  6. 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

Reference

Emacs 29.3 (Org mode 9.6.15)