Essential Comments
A comment earns its place only if a human would lose real context without it.
Match the repo's comment/doc idioms. Never require JSDoc/docstrings or invent a doc system.
Choose scope
- Review: findings only. Noise to delete, missing whys to add; cite symbol and human risk.
- Edit: comments only. Same behavior, structure, names, and APIs.
Keep or add
Only when names and code do not already say it:
- Why / policy - intentional tradeoff, partial success, deliberate swallow
- Invariant / ordering - concurrency, sequence, non-obvious control flow
- External / non-local - vendor quirk, ticket, runbook, magic value whose meaning lives elsewhere
When tightening a good comment, preserve concrete facts (thresholds, ticket IDs, runbook names).
After you write or edit logic, scan once for why / invariant / external facts you actually know (task, ticket, surrounding code) that a later reader cannot recover from names alone. If you know one, add one short comment. Do not guess. If unsure, omit.
Remove
- Narration or English restatement of the next line, name, type, or clear flag
- Docs that only echo identifiers and parameters
- AI / changelog residue and commented-out code (unless the user wants it kept)
- Meta banners; policies or caller roles not evidenced in visible code
- Duplicate decoding of the same magic (at most one short legend at the definition)
Discipline
- Why, not what. If unsure, omit.
- A comment papering over a bad name is a naming issue: say so in review; in comments-only edit, do not rename and do not keep pure narration as a stand-in.
- Ship the diff or findings - no essay.
1---2name: essential-comments3description: Add, keep, or remove code comments so only remarks that help humans remain - why, invariants, tradeoffs, and external constraints - not narration or restated code. Use when cleaning noisy comments, writing new code, reviewing comment quality, or when the user wants fewer/better comments.4---56# Essential Comments78A comment earns its place only if a human would lose real context without it.910Match the repo's comment/doc idioms. Never require JSDoc/docstrings or invent a doc system.1112## Choose scope1314- **Review:** findings only. Noise to delete, missing whys to add; cite symbol and human risk.15- **Edit:** comments only. Same behavior, structure, names, and APIs.1617## Keep or add1819Only when names and code do not already say it:2021- **Why / policy** - intentional tradeoff, partial success, deliberate swallow22- **Invariant / ordering** - concurrency, sequence, non-obvious control flow23- **External / non-local** - vendor quirk, ticket, runbook, magic value whose meaning lives elsewhere2425When tightening a good comment, preserve concrete facts (thresholds, ticket IDs, runbook names).2627After you write or edit logic, scan once for why / invariant / external facts you actually know (task, ticket, surrounding code) that a later reader cannot recover from names alone. If you know one, add one short comment. Do not guess. If unsure, omit.2829## Remove3031- Narration or English restatement of the next line, name, type, or clear flag32- Docs that only echo identifiers and parameters33- AI / changelog residue and commented-out code (unless the user wants it kept)34- Meta banners; policies or caller roles not evidenced in visible code35- Duplicate decoding of the same magic (at most one short legend at the definition)3637## Discipline3839- Why, not what. If unsure, omit.40- A comment papering over a bad name is a naming issue: say so in review; in comments-only edit, do not rename and do not keep pure narration as a stand-in.41- Ship the diff or findings - no essay.
yakoshiq