karitham.dev
a dotfile but it's really big
1---
2name: code-comments
3description: Guide writing high-quality code comments following Ousterhout's principles. Use when writing, reviewing, or improving comments in code. Triggers: "add comments", "how should I comment", "comment this code", "review comments"
4---
5
6## What comments are for
7
8Comments exist to capture information that cannot be expressed in code. If a comment only restates what the code already says, it MUST be deleted because it adds noise without value.
9
10## What to comment
11
12Comments MUST describe things that are not obvious from the code:
13
14- Why a decision was made, not what the code does
15- Units, valid ranges, and data formats
16- Preconditions and postconditions
17- Invariants and non-obvious side effects
18- Edge cases and their handling rationale
19
20Interface comments (on classes, functions, and modules) MUST describe the abstraction — what it does and how to use it — NOT how it is implemented.
21
22Implementation comments SHOULD only appear when the code itself cannot express the intent clearly. If an implementation comment is needed to explain what the code does, the code SHOULD be simplified instead.
23
24## Comment-driven development
25
26Comments MUST be written before the implementation because writing the interface comment first forces clear thinking about the abstraction before committing to code.
27
28If a clean, concise comment cannot be written for a function or module, the design is likely wrong. Treat the difficulty of commenting as a design smell.
29
30Uncommented public interfaces MUST be treated as incomplete, not finished.
31
32## Constraints
33
34- MUST NOT write comments that repeat the code
35- MUST NOT defer comments until after implementation because they become vague and low-value
36- MUST describe the abstraction at the interface level, not the implementation details
37- SHOULD use comments to capture design rationale that would otherwise be lost