write-comment
Installation
SKILL.md
write-comment
Comments exist to say what the code can't. If the code alone answers the question, you don't need a comment. If it doesn't, identify what's missing and pick the type.
The litmus test
Before writing: can the reader understand this without the comment? If yes → delete the comment, improve the name instead. If no → identify the gap below and fill it.
Match the gap to the type
| Information missing | Comment type | Where it goes |
|---|---|---|
| What contract does this function obey, and what are its side effects? | Function | Top of function/type |
| Why this architecture? What alternatives were rejected? | Design | Top of file/package |
| Why this specific line, when something else looks more natural? | Why | Inline, above the line |
| What domain knowledge (math, protocol, algorithm) does the reader need? | Teacher | Inline or top of function |
| If I change this, what else must I update? | Checklist | Inline, as a warning |
| What does this block of 5–20 lines accomplish? (cognitive chunking) | Guide | Inline, above the block |