commenting-style

name	commenting-style
description	Apply when adding, reviewing, or cleaning up code comments — covers commenting classes and methods (not internals), writing for a future LLM reader, and avoiding noise comments on properties or obvious code. Load whenever writing comments or judging whether a comment should exist.

💬 Commenting Style

🎯 The rule

Comment classes and methods. Do NOT comment properties or internal code unless it's genuinely non-obvious.

• ✅ A class comment: what it's responsible for, key decisions, why it exists.
• ✅ A method comment: intent, non-obvious contract, why (not a restatement of the signature).
• ❌ A comment on every property (// the user's id).
• ❌ A comment narrating obvious lines (// loop over items).
• ✅ A comment on a non-obvious internal: a workaround, a tricky invariant, a "why not the obvious way."

🤖 Write for your future LLM self

Comments exist so the next model (or you, later) understands the decisions made — not the mechanics. Capture why this and not the alternative:

/**
 * Places an order: validates the cart, charges via Stripe, then persists.
 * We charge BEFORE writing the order so a declined card never leaves a
 * ghost order row — the DB write is the commit point, payment is the gate.
 */
async place(cart: Cart): Promise<Order> { /* ... */ }

That // We charge BEFORE... line is the gold — it encodes a decision a future reader would otherwise have to reverse-engineer or accidentally break.

✂️ Smell test before writing a comment

Ask: does this comment tell the reader something the code can't? If it just renames the code in English, delete it. If it records a decision, a gotcha, or a "why," keep it.

📐 Mechanics

• JSDoc-style /** */ on classes and exported methods.
• Single-line // for the rare non-obvious internal.
• Keep them current — a stale comment is worse than none.