trim-comments

Trim Comments

Rewrite the comments in scope to be as short as possible while still earning their place. The rules apply to comments in any language.

Options

The user may provide these options inline:

• paths: A path, glob, or file list. Every comment in those files is in scope, changed or not. Without paths, the scope is the comments in or directly above code the current branch changed: committed changes since the base branch, plus staged, unstaged, and untracked files. When the user points at a single comment, that comment is the whole scope.
• --dry-run: Report proposed changes without editing or committing.
• --no-commit: Edit and verify, but leave the edits uncommitted. By default the skill commits its edits, and it never pushes.
• --no-codex: Classify the comments in this session rather than through a Codex dry run; see "Proposals through Codex".

The standard

Lead with what the code is doing. Then the minimum why. Nothing else.

"What" means the effect or purpose a reader cannot get from the next few lines at a glance, not a paraphrase of the statements. A comment whose whole job is a constraint (see "Keep these") leads with the constraint instead.

One line is the default. Two lines when the why genuinely needs a clause. Three or more needs a reason you could defend out loud.

// Bad: why first, action buried, trivia at the end
// multipart/form-data is the documented encoding for this endpoint, and the shape attachments would
// need. Node 22 ships a global FormData.

// Good
// FormData because multipart/form-data is the documented encoding for this endpoint.

Write comments that stay true

A stale comment is worse than none: the reader trusts it, and nothing fails when it drifts. Prefer the wording that will stay true longest, and let that decide between otherwise equal rewrites.

• Anchor the comment to the code beside it, not to code elsewhere. Nearby code changes in the same diff as the comment, so a reviewer sees both. Code elsewhere changes without anyone rereading the comment.
• Never cite line numbers. Any edit above them shifts them. Name a function, type, constant, or file instead, so a rename makes the reference visibly wrong rather than quietly off by a few lines.
• Leave out facts that change on their own schedule: counts of callers or cases, version numbers, dates, "currently", "for now", "new", and lists of the places that use something. The exception is a fact that explains why the code looks the way it does (see "Keep these").
• Prefer a lasting reason to a passing one. "The API rejects more than 3 tags" outlives "the API rejected 4 tags in last week's outage".