Cursor rule

1---
2description: 'Code comment guidelines for all languages'
3globs:
4  - '*'
5alwaysApply: true
6---
7 
8# Code comments
9 
10## Core principles
11 
12- Favor self-documenting code; reach for comments only when the intent or constraints are not obvious from names and structure.
13- Prefer explaining _why_ something exists, the invariants it relies on, or context that comes from outside the code.
14- Avoid comments that simply restate the implementation, mirror type annotations, or paraphrase variable names.
15- Delete or update comments whenever behavior changes — stale commentary is worse than none.
16 
17## When comments add value
18 
19- **Domain or business context**: capture rules, policies, or edge cases not evident from code.
20- **Non-obvious algorithms or patterns**: explain unconventional control flow or defensive code paths.
21- **Integration nuances**: document assumptions about external systems or data contracts.
22- **Preconditions and invariants**: call out expectations that guide safe use.
23- **Suppressed warnings**: pair `// @ts-expect-error` or lint suppressions with a justification.
24 
25Use TSDoc/JSDoc blocks sparingly for exported symbols when consumers need extra context beyond the type signature.
26 
27## When comments are harmful
28 
29- Obvious statements about what the code already says.
30- Duplicating type information or parameter descriptions.
31- Narrating straightforward control flow without additional insight.
32- Commented-out code; rely on version control history.
33 
34## Hygiene
35 
36- Re-evaluate comments during code reviews and refactors.
37- Do not include secrets, tokens, or sensitive identifiers.
38- Reference external resources with stable links when they inform behavior.
39- If a comment documents a temporary workaround, annotate it with the issue that will remove it.
40