Code comments cleanup

Cleans up code comments - removes noise that restates the code, keeps and sharpens why-comments, fixes stale comments that lie, and adds a comment only where intent is non-obvious. Use when asked to tidy, review or improve comments in a file, module or diff.

DocumentationPack: Documentation78 linescode-comments-cleanup

Install

Run one command — it saves SKILL.md into your agent's skills folder. Restart the agent and the skill is picked up automatically.

Claude Code — macOS, Linux
mkdir -p ~/.claude/skills/code-comments-cleanup && curl -fsSL https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md -o ~/.claude/skills/code-comments-cleanup/SKILL.md
Codex, Cursor — macOS, Linux
mkdir -p ~/.agents/skills/code-comments-cleanup && curl -fsSL https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md -o ~/.agents/skills/code-comments-cleanup/SKILL.md
Claude Code — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.claude\skills\code-comments-cleanup" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md -UseBasicParsing -OutFile "$HOME\.claude\skills\code-comments-cleanup\SKILL.md"
Codex, Cursor — Windows PowerShell
New-Item -ItemType Directory -Force "$HOME\.agents\skills\code-comments-cleanup" | Out-Null; Invoke-WebRequest https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md -UseBasicParsing -OutFile "$HOME\.agents\skills\code-comments-cleanup\SKILL.md"

Any other agent: save the file into its skills folder, or give it the link to the file: https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md

SKILL.md

Raw

Code Comments Cleanup

Good comments explain what the code cannot say: why it is this way, what constraint it works around, what would break. Everything else is noise or a future lie. Change comments only; never change code behavior in this task.

Workflow

  1. Determine scope: the files or diff the user named. Do not sweep the whole repository unasked. Check git status so you know which changes are yours.
  2. Read each file's code first, then its comments. A comment can only be judged against the code beside it.
  3. Classify every comment into one of the buckets below and act on it.
  4. Make the edits. Touch only comment lines and blank lines directly around them.
  5. Verify nothing else changed: review git diff and confirm every changed line is a comment. Run the formatter, linter and tests if the project has them, because comment syntax mistakes (unclosed block comment, broken docstring) can break a build.

Buckets

Remove (noise)

  • Restates the code: // increment i above i++, # return the user above return user.
  • Section banners and decorative separators that add nothing.
  • Commented-out code. Version control already keeps it. If it might be wanted, ask the user before deleting a large block.
  • Changelog or author notes inside files ("added by X on date"); history lives in git.
  • Empty or boilerplate docstrings generated from templates ("Constructor.", "Gets the name.").

Fix (stale or wrong)

  • Comments that disagree with the code: wrong parameter names, outdated behavior, references to removed functions, wrong units. Verify against the code, then rewrite to match it. If the code looks wrong rather than the comment, do not change the code; report it to the user.
  • TODOs that are already done or reference a gone ticket. Remove the done ones; for open ones, keep and add context if known.

Keep and sharpen (intent)

  • Why: a workaround, a surprising constraint, a protocol or legal requirement, a performance trade-off, an ordering dependency.
  • Warnings: thread-safety, side effects, units, invariants, "do not reorder".
  • Public API docs where the project uses doc comments: what it does, parameters, return value, errors, and an example when usage is not obvious.
  • References: a link to the spec, issue or bug that explains a strange line (keep links that are official specs or the project's own tracker).

Add (only if needed)

  • Non-obvious intent: a regular expression, bit manipulation, a magic number, a tricky algorithm, a deliberate empty catch, a non-obvious default.
  • Prefer renaming over commenting when a better name would remove the need; propose the rename to the user instead of making it.

Examples

// before: noise
// loop over the users
for (const u of users) { ... }

// before: stale
// returns null when the user is missing
function getUser(id) { /* now throws NotFoundError */ }

// after: why
// Retry once: the billing API returns 502 on a cold start.

Fix the stale one by describing the thrown error, not by changing the code.

Style

  • One short sentence beats a paragraph. Write the reason first: "Retry once because the API returns 502 on cold start."
  • Use the file's existing comment style and doc-comment format (JSDoc, docstrings, Javadoc, godoc conventions such as starting with the identifier name).
  • No jokes, no names of people, no emotion, no "obviously" or "simply".
  • Keep language consistent with the surrounding comments.
  • A TODO needs an owner or ticket if the project uses that convention: TODO(KEY-123): ....

Pitfalls

  • Deleting a comment that explains a hidden constraint just because the code looks self-explanatory. If unsure whether it is noise, keep it and flag it.
  • Inventing a reason. If you cannot tell why the code is that way, write a question for the user or leave a TODO: confirm why ... rather than a made-up explanation.
  • Touching generated files, vendored code or license headers.
  • Reformatting or reflowing code while editing comments.
  • Removing directive comments that tools read: eslint-disable, noqa, type: ignore, //go:generate, # pragma, @ts-expect-error, shebangs, encoding lines, license identifiers.

Report back

Counts per bucket (removed, fixed, kept, added), the list of comments that revealed a probable code bug, questions where intent could not be determined, and confirmation that the diff contains only comment changes and the checks passed.

Source: AnyModel skills catalog · License: CC BY 4.0

Connect through AnyModel API

This skill runs on whatever model your agent uses. Point Claude Code, Codex or Cursor at AnyModel to run it on Claude, GPT, Gemini and more with one key — pay per token, no subscription.

More from the pack Documentation