Clean Comments
Clean up code comments so each one earns its place. The standard is John
Ousterhout's, from A Philosophy of Software Design: code is the description of
what happens; a comment exists to capture the things the code cannot say.
A comment that just restates the code adds reading cost and zero information, and
drifts out of date. Removing it is an improvement, not a loss.
This is the audit-time half of the contract; write-comments is the write-time
half. This skill changes comments (and, when low-risk, names). It must not change
behavior.
House conventions, if the repository has them
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Conventions folder (
docs/agents/workspace.md). Default: none. If one is
configured and holds a comment or code-style convention, read it first: where
it is stricter or more specific than this skill, it wins.
The one test for every comment
Does this comment tell a competent reader something the code itself does not
already make obvious?
If yes, keep it (sharpen it if it is verbose or pitched too low). If no, delete
it. "Obvious" is judged against the actual code in front of you and a reader
fluent in the language, not against a beginner.
What good comments carry (KEEP / SHARPEN these)
These hold information that is genuinely absent from the code:
- Why, not what. The reason a thing is done this way: the tradeoff, the
constraint, the bug being avoided, the spec or rule being honored.
- Intent at a higher abstraction. One line that says what a block
accomplishes, so a reader does not have to reverse-engineer it from the
statements. Comments should sit above the code's level of abstraction.
- Interface contracts. For an exported function or type: what it does for
the caller, the meaning of params and return, side effects, thrown errors, and
preconditions. Written for someone who will not read the body.
- Invariants, units, ranges, and non-obvious consequences. "milliseconds",
"caller must hold the lock", "must stay in sync with X", "0 means unbounded".
- Gotchas and cross-references. "load-bearing: removing this breaks Y",
"mirrors the values in Z", links to a ticket, spec or decision record.
When such a comment is correct but bloated, repeats the code partway, or narrates
line by line, SHARPEN it: keep the signal (the why, intent, contract), cut the
restatement, raise it to the right abstraction level.
What to REMOVE
- Restatement of the code.
// increment i over i++; // the user over a
user variable; // loop over items over an obvious for (const item of …);
a JSDoc @param userId The user id that adds nothing past the typed signature.
- Name-echo doc comments. A doc comment that only re-says the identifier it
sits on:
/** Smooth-scroll configuration. */ over const SMOOTH_SCROLL = …,
/** The locale list. */ over LOCALES, /** scrub */ over scrub: 0.6. The
name already says it. Keep only if the comment adds a contract, units, range,
or why the value is what it is.
- Decorative banners and section dividers.
/* ---- Colors ---- */,
// ===== Helpers =====, box-drawing separators. They are navigation noise;
structure and grouping should carry this, not ASCII art.
- Commented-out code. Version control already remembers it.
- Changelog and attribution narration in code. "Added by … on …",
"TODO(2019): refactor" with no actionable content. Keep actionable TODOs that
name a real follow-up; consider tightening them.
- Stale or wrong comments that no longer match the code. They mislead human
readers and derail agents that act on them. Removing a lie beats keeping it;
replace it with a correct comment only if the corrected version passes the one
test above.
Be thorough, not timid
Ousterhout is pro good comments (especially interface comments and "why"); the
goal is not the fewest comments, it is comments that all pull their weight. But do
not let "it might be useful" preserve noise. Two specific habits to correct:
- Trim multi-line headers to the signal. A 5-line file or function header
that carries one real idea should become 1-2 lines. Keep the why and the
contract; cut the wind-up, the restatement of the name, and the "this file
contains…" preamble. A header is not a place to relax the one test.
- Default to REMOVE for the name-echo and banner patterns above. These are
the comments that most often survive a timid pass. If your summary shows almost
nothing removed across many files, re-read with a sharper eye: real codebases
written quickly almost always carry some restatement and some banners.
The bar is unchanged (does it say something the code does not), but apply it
without flinching.
Never touch these (load-bearing, machine-read, or legal)
Treat as untouchable even when they look like "just a comment":
- Linter and tool directives:
eslint-disable*, // @ts-expect-error,
// @ts-ignore, // @ts-nocheck, biome-ignore, prettier-ignore,
// istanbul ignore, /* c8 ignore */, # type: ignore, # noqa,
# pragma, // deno-lint-ignore, and the like.
- Codegen and tooling markers:
@generated, region markers a tool consumes,
OpenAPI or JSDoc annotations a build step reads.
- Shebangs (
#!/usr/bin/env node), license and copyright headers, SPDX tags.
- JSX comments
{/* … */} that affect what renders, and HTML conditional
comments.
- Anything whose removal could change compilation, linting, bundling, or output.
If unsure whether a comment is load-bearing, keep it: the cost of a wrong
deletion here far exceeds the cost of a surviving comment.
Names over comments
When a comment exists only to explain what an unclear name means
(// elapsed time in ms over let t), the better fix is the name itself
(let elapsedMs). Prefer the rename when it is local and low-risk (a local
variable, a private helper, a parameter), apply it, and drop the crutch comment.
For anything exported or widely referenced, do not rename silently: flag it
as a suggested rename in the report and leave the comment until the rename is
made deliberately, because the blast radius is the user's call. A rename is the
only non-comment edit this skill may make, and only when it is safe and
behavior-preserving.
Workflow
Resolve the target. One of:
- a changeset:
git diff --staged --name-only (or git diff --name-only, a
commit range, or a PR the user names);
- an explicit list of files; or
- a directory (walk it for source files).
With no scope given, ask the user which, using your structured-question tool
if you have one; otherwise list numbered options in plain text and stop until
they reply. Review only source files with comment syntax. Skip lockfiles,
generated output, vendored code, binaries, and dependency folders such as
node_modules. Review only the files in scope, not the whole repository,
unless asked.
Read each file fully before editing. Context decides whether a comment is
obvious or load-bearing. Be language-aware about comment syntax:
// and /* */ (TS/TSX/JS/CSS/Java/Go/Rust/C), # (YAML/Python/shell/TOML),
<!-- --> (Markdown/HTML), {/* */} (JSX), -- (SQL/Lua). In CSS, /* */
is the only form; in Markdown, prose is the content, so only touch HTML-comment
cruft, not the document body.
Classify every comment as KEEP, SHARPEN, or REMOVE using the rules above.
For name-compensating comments, decide RENAME (safe and local) or FLAG
(exported).
Apply the edits. Comments only, plus safe local renames. Make minimal,
surgical changes; do not reflow unrelated code. Preserve the file's existing
comment style and indentation.
Verify you changed nothing that runs. Read the diff back: it should be
comments and, at most, safe renames. If a "comment" turned out to be a
directive, revert it.
Style for any comment you write or sharpen
- Plain, direct, lower-jargon. Say the why in as few words as carry it.
- No false precision; use ranges where uncertainty is real.
- Match the file's existing comment style, and the conventions folder where one
is configured.
Report
After editing, output a concise summary so the user can see what changed and why.
End with this structure:
## Comment cleanup summary
| File | Kept | Sharpened | Removed | Renames |
|------|-----:|----------:|--------:|--------:|
| path/to/file.ts | 4 | 1 | 3 | 1 |
| ... | | | | |
| Total | N | N | N | N |
### Notable changes
- path/to/file.ts: removed 3 restatement comments; sharpened the header to state
the "why" and dropped the line-by-line narration.
### Suggested renames (not applied: exported / wide blast radius)
- path/to/api.ts:42 `t` -> `elapsedMs` (exported; rename deliberately)
### Untouched directives (left intact on purpose)
- path/to/config.ts: `@ts-expect-error` on the untyped plugin import
If there were no comments worth changing in a file, say so rather than inventing
work. The goal is comments that pull their weight, not the fewest comments.
1---2name: clean-comments3description: >-4 Audit and repair EXISTING code comments so each says what the code cannot (intent,5 rationale, invariants, units, gotchas) and none restates it: delete restatement, banners6 and commented-out code, fix stale or wrong comments, sharpen bloated ones. Use whenever7 the user asks to clean up, audit, review or fix comments, remove redundant or obvious8 comments, tidy doc comments or docstrings, strip commented-out code, "make comments9 follow Ousterhout", or improve comment quality across a file, a directory, or a10 changeset (staged diff, commit range, PR), even if they only say "the comments need11 work". Do NOT use for comments on code you are writing right now (use `write-comments`).12license: MIT13argument-hint: '[optional: files, a directory, or "staged" / a commit range / a PR to scope to]'14metadata:15 source: https://skillmd.com/skills/spencermarx/clean-comments16 ideas: "John Ousterhout's A Philosophy of Software Design"17---1819# Clean Comments2021Clean up code comments so each one earns its place. The standard is John22Ousterhout's, from _A Philosophy of Software Design_: code is the description of23_what happens_; a comment exists to capture the things the code **cannot** say.24A comment that just restates the code adds reading cost and zero information, and25drifts out of date. Removing it is an improvement, not a loss.2627This is the audit-time half of the contract; `write-comments` is the write-time28half. This skill changes comments (and, when low-risk, names). It must not change29behavior.3031## House conventions, if the repository has them3233This repository's agent configuration should have been provided to you (the34`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the35defaults below and suggest the user run the `setup-aclarify-skills` skill.3637- **Conventions folder** (`docs/agents/workspace.md`). Default: none. If one is38 configured and holds a comment or code-style convention, read it first: where39 it is stricter or more specific than this skill, it wins.4041## The one test for every comment4243> Does this comment tell a competent reader something the code itself does not44> already make obvious?4546If yes, keep it (sharpen it if it is verbose or pitched too low). If no, delete47it. "Obvious" is judged against the actual code in front of you and a reader48fluent in the language, not against a beginner.4950## What good comments carry (KEEP / SHARPEN these)5152These hold information that is genuinely absent from the code:5354- **Why, not what.** The reason a thing is done this way: the tradeoff, the55 constraint, the bug being avoided, the spec or rule being honored.56- **Intent at a higher abstraction.** One line that says what a block57 accomplishes, so a reader does not have to reverse-engineer it from the58 statements. Comments should sit _above_ the code's level of abstraction.59- **Interface contracts.** For an exported function or type: what it does for60 the caller, the meaning of params and return, side effects, thrown errors, and61 preconditions. Written for someone who will not read the body.62- **Invariants, units, ranges, and non-obvious consequences.** "milliseconds",63 "caller must hold the lock", "must stay in sync with X", "0 means unbounded".64- **Gotchas and cross-references.** "load-bearing: removing this breaks Y",65 "mirrors the values in Z", links to a ticket, spec or decision record.6667When such a comment is correct but bloated, repeats the code partway, or narrates68line by line, **SHARPEN** it: keep the signal (the why, intent, contract), cut the69restatement, raise it to the right abstraction level.7071## What to REMOVE7273- **Restatement of the code.** `// increment i` over `i++`; `// the user` over a74 `user` variable; `// loop over items` over an obvious `for (const item of …)`;75 a JSDoc `@param userId The user id` that adds nothing past the typed signature.76- **Name-echo doc comments.** A doc comment that only re-says the identifier it77 sits on: `/** Smooth-scroll configuration. */` over `const SMOOTH_SCROLL = …`,78 `/** The locale list. */` over `LOCALES`, `/** scrub */` over `scrub: 0.6`. The79 name already says it. Keep only if the comment adds a contract, units, range,80 or why the value is what it is.81- **Decorative banners and section dividers.** `/* ---- Colors ---- */`,82 `// ===== Helpers =====`, box-drawing separators. They are navigation noise;83 structure and grouping should carry this, not ASCII art.84- **Commented-out code.** Version control already remembers it.85- **Changelog and attribution narration in code.** "Added by … on …",86 "TODO(2019): refactor" with no actionable content. Keep actionable TODOs that87 name a real follow-up; consider tightening them.88- **Stale or wrong comments** that no longer match the code. They mislead human89 readers and derail agents that act on them. Removing a lie beats keeping it;90 replace it with a correct comment only if the corrected version passes the one91 test above.9293## Be thorough, not timid9495Ousterhout is _pro_ good comments (especially interface comments and "why"); the96goal is not the fewest comments, it is comments that all pull their weight. But do97not let "it might be useful" preserve noise. Two specific habits to correct:9899- **Trim multi-line headers to the signal.** A 5-line file or function header100 that carries one real idea should become 1-2 lines. Keep the why and the101 contract; cut the wind-up, the restatement of the name, and the "this file102 contains…" preamble. A header is not a place to relax the one test.103- **Default to REMOVE for the name-echo and banner patterns above.** These are104 the comments that most often survive a timid pass. If your summary shows almost105 nothing removed across many files, re-read with a sharper eye: real codebases106 written quickly almost always carry some restatement and some banners.107108The bar is unchanged (does it say something the code does not), but apply it109without flinching.110111## Never touch these (load-bearing, machine-read, or legal)112113Treat as untouchable even when they look like "just a comment":114115- Linter and tool directives: `eslint-disable*`, `// @ts-expect-error`,116 `// @ts-ignore`, `// @ts-nocheck`, `biome-ignore`, `prettier-ignore`,117 `// istanbul ignore`, `/* c8 ignore */`, `# type: ignore`, `# noqa`,118 `# pragma`, `// deno-lint-ignore`, and the like.119- Codegen and tooling markers: `@generated`, region markers a tool consumes,120 OpenAPI or JSDoc annotations a build step reads.121- Shebangs (`#!/usr/bin/env node`), license and copyright headers, SPDX tags.122- JSX comments `{/* … */}` that affect what renders, and HTML conditional123 comments.124- Anything whose removal could change compilation, linting, bundling, or output.125126If unsure whether a comment is load-bearing, keep it: the cost of a wrong127deletion here far exceeds the cost of a surviving comment.128129## Names over comments130131When a comment exists only to explain what an unclear name means132(`// elapsed time in ms` over `let t`), the better fix is the name itself133(`let elapsedMs`). Prefer the rename when it is local and low-risk (a local134variable, a private helper, a parameter), apply it, and drop the crutch comment.135For anything exported or widely referenced, do **not** rename silently: flag it136as a suggested rename in the report and leave the comment until the rename is137made deliberately, because the blast radius is the user's call. A rename is the138only non-comment edit this skill may make, and only when it is safe and139behavior-preserving.140141## Workflow1421431. **Resolve the target.** One of:144 - a changeset: `git diff --staged --name-only` (or `git diff --name-only`, a145 commit range, or a PR the user names);146 - an explicit list of files; or147 - a directory (walk it for source files).148149 With no scope given, ask the user which, using your structured-question tool150 if you have one; otherwise list numbered options in plain text and stop until151 they reply. Review only source files with comment syntax. Skip lockfiles,152 generated output, vendored code, binaries, and dependency folders such as153 `node_modules`. Review only the files in scope, not the whole repository,154 unless asked.1551562. **Read each file fully before editing.** Context decides whether a comment is157 obvious or load-bearing. Be language-aware about comment syntax:158 `//` and `/* */` (TS/TSX/JS/CSS/Java/Go/Rust/C), `#` (YAML/Python/shell/TOML),159 `<!-- -->` (Markdown/HTML), `{/* */}` (JSX), `--` (SQL/Lua). In CSS, `/* */`160 is the only form; in Markdown, prose is the content, so only touch HTML-comment161 cruft, not the document body.1621633. **Classify every comment** as KEEP, SHARPEN, or REMOVE using the rules above.164 For name-compensating comments, decide RENAME (safe and local) or FLAG165 (exported).1661674. **Apply the edits.** Comments only, plus safe local renames. Make minimal,168 surgical changes; do not reflow unrelated code. Preserve the file's existing169 comment style and indentation.1701715. **Verify you changed nothing that runs.** Read the diff back: it should be172 comments and, at most, safe renames. If a "comment" turned out to be a173 directive, revert it.174175## Style for any comment you write or sharpen176177- Plain, direct, lower-jargon. Say the why in as few words as carry it.178- No false precision; use ranges where uncertainty is real.179- Match the file's existing comment style, and the conventions folder where one180 is configured.181182## Report183184After editing, output a concise summary so the user can see what changed and why.185End with this structure:186187```188## Comment cleanup summary189190| File | Kept | Sharpened | Removed | Renames |191|------|-----:|----------:|--------:|--------:|192| path/to/file.ts | 4 | 1 | 3 | 1 |193| ... | | | | |194| Total | N | N | N | N |195196### Notable changes197- path/to/file.ts: removed 3 restatement comments; sharpened the header to state198 the "why" and dropped the line-by-line narration.199200### Suggested renames (not applied: exported / wide blast radius)201- path/to/api.ts:42 `t` -> `elapsedMs` (exported; rename deliberately)202203### Untouched directives (left intact on purpose)204- path/to/config.ts: `@ts-expect-error` on the untyped plugin import205```206207If there were no comments worth changing in a file, say so rather than inventing208work. The goal is comments that pull their weight, not the fewest comments.