code-comment-style

name

code-comment-style

description

Audit inline code comments against Jack's terse "why not what" discipline and trim the offenders. Use on demand for a dedicated comment pass over recent changes. Triggers on "check comment style", "review comments", "comment audit", "are these comments ok", "trim comments", "audit my comments". Also run as a final self-check after writing a chunk of code. NOT a substitute for the always-on CLAUDE.md inline-comment rule (that governs writing; this is for auditing).

code-comment-style

Enforce Jack's inline-comment discipline: a comment earns its place only by saying why, briefly. Everything else is noise the reader has to skim past.

The rule (from CLAUDE.md)

• 1-2 lines max. More than that, the comment is doing the commit body's job.
• Explain why, not what. The code already says what it does.
• Delete mechanic-recaps. If a comment restates the line below it (loop, assignment, flag list, function signature/type), cut it.
• Just solved something subtle? The investigation narrative belongs in the commit body / PR description, NOT an inline block. The comment keeps only the 1-2 line why.

Exceptions (leave these alone)

• Pipeline of transforms: a short bullet per step is fine.
• Public-API JSDoc: may go longer for a non-obvious contract (invariants, units, ownership, gotchas a caller can't see).

Process

1. Scope the comments. Default to added/changed comment lines in git diff (unstaged) and git diff --cached. If the user names files or a commit, use those. Look only at comments, not the code.
2. Flag each comment against the checklist:
   • Over 2 lines (and not a JSDoc/pipeline exception).