Чистка комментариев в коде

Чистит комментарии в коде: убирает шум, повторяющий код, сохраняет и уточняет комментарии «почему», исправляет устаревшие, которые врут, и добавляет комментарий только там, где замысел неочевиден. Используйте, когда просят привести в порядок или проверить комментарии в файле, модуле или diff.

ДокументацияПак: Документация78 строкcode-comments-cleanup

Установка

Выполните одну команду — она сохранит SKILL.md в папку скиллов агента. Перезапустите агента, и он подхватит скилл сам.

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"

Другой агент: сохраните файл в его папку скиллов или дайте ему ссылку на файл: https://anymodel.org/en/skills/docs/code-comments-cleanup/SKILL.md

SKILL.md

Исходник

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

Подключить через AnyModel API

Скилл работает на той модели, которую использует агент. Подключите Claude Code, Codex или Cursor к AnyModel и запускайте его на Claude, GPT, Gemini и других моделях по одному ключу — оплата за токены, без подписки.

Ещё из пака Документация

Написание README

Пишет или чинит README по реальному коду: что это за проект, рабочий быстрый старт с проверенными командами, таблица конфигурации, частые задачи и решение проблем – без выдуманных возможностей. Используйте, когда у репозитория нет README, он устарел или пользователь просит документацию проекта.

Документация HTTP API

Документирует HTTP-эндпоинты по реальному коду: метод, путь, авторизация, параметры, примеры запросов и ответов, коды ошибок – примеры совпадают с настоящими обработчиками. Используйте, когда у сервиса нет документации API, она устарела или пользователь просит описать API.

Запись архитектурного решения (ADR)

Пишет короткую датированную запись архитектурного решения (ADR): контекст, решение, рассмотренные варианты с компромиссами, последствия и статус, и кладёт её рядом с кодом. Используйте, когда принято или обсуждается важное техническое решение, которое нужно зафиксировать.