comments · diff
git:20260507.7523b16 to git:20260512.5fd702f
27 added, 64 removed. Audit A to A.
---
name: comments
- description: Decide whether a comment is needed and write a useful one when it is — focused on the "why" behind non-obvious code, not narration of what the code does. Use this skill when adding or editing comments, reviewing a diff for excess commentary, cleaning up "AI thought" trails, writing doc comments for public APIs, or when the user pushes back on noisy/redundant comments.
+ description: Scan recently written or edited code and remove comments that do not earn their place — narration, step markers, task/PR references, commented-out blocks, decorative banners. Use this skill after finishing a non-trivial code change, when reviewing a diff for comment hygiene, when the user mentions noisy or redundant comments, or proactively before declaring a coding task complete. Defer to the `comments` rule for what makes a comment worth keeping.
---
- # Comments
-
- Decide whether a comment belongs, then make the comment earn its place.
-
- ## Steps
-
- 1. **Try removing the comment first.** Read the line(s) without it. If a competent reader still understands the code, leave the comment out.
- 2. **Rename before commenting.** If the intent is unclear, the fix is usually a sharper identifier (`isExpired` beats `// check if expired`). Reach for a comment only when naming and structure can't carry the meaning.
- 3. **Identify the _why_.** A comment belongs when it captures something the code itself cannot show:
- - a hidden constraint or invariant
- - an external quirk (API behavior, browser bug, ordering requirement)
- - a workaround for a known issue (name the issue)
- - a surprise the reader would otherwise question
- 4. **Write it tight.** One line where possible. State the reason, not the mechanism. Skip phrases like "this function…" or "we will now…".
- 5. **Public APIs get doc comments.** Document the contract — inputs, outputs, thrown errors, side effects — using the language's doc syntax (`///`, `/** */`, docstrings). Leave internal helpers quiet unless they hide a non-obvious constraint.
- 6. **Match the codebase.** Before adding comments to a new area, read 5–10 nearby files. Mirror their comment density, tone, and doc-comment style.
-
- ## Anti-pattern: narration & AI thought trails
-
- ```ts
- // Step 1: get users
- const users = await fetchUsers();
+ # Comments Cleanup
- // loop through users
- for (const u of users) {
- // validate user
- if (u.isValid) {
- save(u); // save to db
- }
- }
+ Scan the diff you just produced and strip comments that the code already carries. The `comments` rule has the long-form criteria and examples; this skill is the cleanup procedure.
- // AI thought: this handles the empty case
- if (users.length === 0) return;
+ ## Procedure
- // old logic — keep just in case
- // function oldThing() { ... }
- ```
+ 1. **Pull the diff.** `git diff` for unstaged work, `git diff --staged` for staged. Focus on `+`-lines that introduced comments.
+ 2. **For each new comment, ask one question** — *would a competent reader miss anything if this comment were removed?* If the answer is no, delete the comment.
+ 3. **Tighten what remains.** A comment that stays should describe *why*, fit on one line where possible, and use the language's doc-comment syntax for public APIs only.
- This narrates what the code already says, leaves planning markers, and keeps dead code "just in case". Strip it.
+ ## Categories to delete on sight
- ## Pattern: doc the contract, capture the surprise
+ - **Narration** — restates what the code does (`// increment counter`, `// loop through users`, `// validate user`).
+ - **Step markers** — planning artefacts (`// Step 1: fetch users`, `// now we will…`, `// AI thought: …`).
+ - **Task / PR / caller references** (`// added for ticket X`, `// used by Y`) — that context belongs in the commit message.
+ - **Commented-out code** — git keeps the history.
+ - **Decorative banners** (`// ===== HELPERS =====`) when nothing else in the file uses them.
+ - **Apologies** (`// hacky but works`) — either fix the code or open a tracked issue and link it.
+ - **Untracked `TODO` / `FIXME`** — pair every marker with an owner or an issue, or resolve it now.
- ```ts
- /**
- * Synchronizes user records with the remote backend.
- *
- * Throws SyncError if the network fails or the payload is malformed.
- */
- async function syncUsers(): Promise<void> {
- // Backend returns 404 for "no data yet" on freshly provisioned accounts —
- // treat it as an empty result, not an error.
- try {
- await api.fetch();
- } catch (e) {
- if (isNotFound(e)) return;
- throw e;
- }
- }
+ ## Categories to keep
- // Self-explanatory — leave it alone.
- const isAdult = (user: User) => user.age >= 18;
- ```
+ - **Hidden constraint** — a non-obvious invariant, ordering requirement, or performance assumption.
+ - **External quirk** — API behaviour, browser bug, platform-specific oddity (name the system).
+ - **Workaround** — a fix for a tracked upstream issue (link it).
+ - **Surprise** — behaviour that would make a reasonable reader pause.
+ - **Public API contract** — inputs, outputs, errors, side effects via `///`, `/** */`, or docstrings.
- The doc comment states the contract; the inline comment captures a non-obvious upstream quirk; trivial code is left to speak for itself.
+ ## Self-check before finishing
- ## Edge cases
+ - Diff scanned end-to-end, including test files.
+ - No `// Step N`, no `// loop`, no `// AI thought`, no commented-out blocks.
+ - Every remaining `TODO` / `FIXME` has an owner or issue.
+ - Comment density matches the surrounding files (scan 5–10 nearby).
- - **Apologies in code** ("// hacky but works") — fix the code or file a tracked issue; let the comment go.
- - **Task / PR / caller references** ("// added for ticket X", "// used by Y") — keep that context in the commit message; the source of truth shouldn't follow the work item around.
- - **`TODO` / `FIXME` markers** — pair every one with an owner or a tracked issue, or resolve it now.
- - **Translating code line-by-line into English (or any language)** — that's narration. Comment a constraint or a surprise instead, or remove the comment entirely.
- - **Section banners** (`// ===== HELPERS =====`) — match the file: use them when nearby files already do, leave them out when they don't.
- - **Commented-out code** — delete it. Git keeps history.
+ Report what was removed and what was kept, with a one-line reason per surviving comment when it isn't obvious.