| name | commenting-style |
| description | Apply whenever you write or modify ANY class, method, or .ts file — not only when editing comments. Every class and method you author must be commented per this skill, so load it alongside code-architecture during all code-writing. Covers commenting classes and methods (not internals), writing for a future LLM reader, and avoiding noise comments on properties or obvious code. |
💬 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:
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.
🔗 Related skills
This skill pairs with code-architecture, which is the entry point for writing code and lists class/method comments among its required class conventions. If you're building a class or service, both skills apply together — and testing-standards for its /tests coverage.
