| name | comments |
| description | Apply when writing, reviewing, or removing comments. Triggers: /comments, "should I comment this", "is this comment good", "explain why this code does X". |
Comments
Default: no comment. A comment that explains a what readers deduce from names + types must be deleted or replaced by a better name.
Comments explain WHY. Never WHAT.
Decision flow
- Obvious from names + types? → no comment
- What obvious, why hidden? → maybe
- Better name would fix it? → rename instead
- Why comes from a hidden constraint (FK choice, race, business rule, workaround)? → comment justified
- Algorithm/semantics genuinely tricky? → comment + tiny example
- Still in doubt? → don't comment
When a comment IS justified
Six categories. Anything outside → delete.
- Non-obvious invariants. Data property the code relies on but doesn't enforce locally.
"endTime is computed at booking time and frozen on the row."
- Choice rationale where the alternative is plausible. Always pair with the rejected option.
"RESTRICT (not CASCADE): hard-deleting a city referenced by areas must surface the dependency, not silently orphan rows."
- Subtle semantics + tiny example. Reserve for math/time/concurrency.
"Half-open
[start, end) — 10:00–10:30 and 10:30–11:00 touch but never overlap."
- External / business constraints. Regulation, partner API, ops decision. Name the constraint, not the ticket.
"Wallet operations must run inside a SERIALIZABLE transaction."
- Surprising behaviour readers will misread.
"Returns null (not throws) when the photo key is empty — callers rely on null for default avatar."
- TODO/FIXME with concrete follow-up.
// TODO(<scope>): <action> after <trigger> / // FIXME(<scope>): <symptom>. Never // TODO: fix later.
Delete on sight
- Restating the code (
// increment counter above counter++).
- Naming the caller or current task (
// used by the user login flow, // added for ticket NEST-417).
- History (
// removed legacy retry block, // was 30s before). Git knows.
- Closing-brace labels (
} // end of if).
- Section banners with no payload (
// ===== HELPERS =====).
@author / @since / @version tags.- Apologies / chatter (
// sorry this is ugly).
- Commented-out code.
- Arabic gloss of English identifiers.
- Type restatement (
// returns a number above : number).
- Defensive narration (
// this should never happen — prove it can't and remove the throw).
Details (load on demand)
- Shape, length, doc comments → @shape.md
- Project-specific conventions (voice, dividers, i18n, migrations, decorators, tests) → @conventions.md
- Review checklist + templates + usage modes → @review.md
See also
- @../naming-conventions/SKILL.md — better names usually replace comments
Related memory: [[feedback_no_unrequested_logger]], [[feedback_translation_keys]].
