Code documentation
The code says what happens. Documentation exists for everything else: why,
when, what must stay true, and what will bite. Write for the maintainer at
their moment of confusion.
Method
- Comment the why, never the what. "Retry three times" restates the
loop; "the vendor API drops roughly 1 in 50 calls under load, and three
retries brings failure below our SLO" earns its bytes. Before writing a
comment, ask what the reader cannot learn from the code below it.
- Document the contract at every public boundary: what the function
promises, what it requires, what happens on bad input, whether it is
safe to call twice, what it costs (network? blocking? allocation-heavy?).
Private helpers usually need a good name more than a docstring.
- Mark the landmines explicitly. Ordering requirements ("must run
after migrations"), units ("milliseconds"), thread-safety, the reason a
simpler approach was rejected. These comments prevent the confident
refactor that breaks production.
- Keep examples honest and runnable. One realistic call with its
actual result beats three paragraphs. If the example cannot be tested,
it will drift; prefer examples that live in tests or doctests.
- Delete lies on sight. A comment contradicting the code is worse
than none, because half the readers will trust it. Editing code means
auditing its comments in the same change.
- Match the house style: the project's docstring format, tone, and
density. A file where every second line is commented reads as noise;
one comment on the genuinely surprising line reads as a flare.
What not to write
- Restatements: "increment i by one".
- Changelogs in comments: version control already remembers.
- Commented-out code: delete it; the attic is git.
- Apologies without information: "hack, sorry" helps nobody, while
"workaround for framework issue #4182, removable at v3" is a plan.
Litmus test
Cover the code and read only the comments and names: do you know what this
module is for, what its edges are, and what you must not break? Then cover
the comments: does anything in the code surprise you that a comment should
have flagged?
1---2name: code-documentation3description: Write code comments and API docs that carry what the code cannot say, and nothing it already does. Use when documenting functions, modules, or tricky passages.4---56# Code documentation78The code says what happens. Documentation exists for everything else: why,9when, what must stay true, and what will bite. Write for the maintainer at10their moment of confusion.1112## Method13141. **Comment the why, never the what.** "Retry three times" restates the15 loop; "the vendor API drops roughly 1 in 50 calls under load, and three16 retries brings failure below our SLO" earns its bytes. Before writing a17 comment, ask what the reader cannot learn from the code below it.182. **Document the contract at every public boundary:** what the function19 promises, what it requires, what happens on bad input, whether it is20 safe to call twice, what it costs (network? blocking? allocation-heavy?).21 Private helpers usually need a good name more than a docstring.223. **Mark the landmines explicitly.** Ordering requirements ("must run23 after migrations"), units ("milliseconds"), thread-safety, the reason a24 simpler approach was rejected. These comments prevent the confident25 refactor that breaks production.264. **Keep examples honest and runnable.** One realistic call with its27 actual result beats three paragraphs. If the example cannot be tested,28 it will drift; prefer examples that live in tests or doctests.295. **Delete lies on sight.** A comment contradicting the code is worse30 than none, because half the readers will trust it. Editing code means31 auditing its comments in the same change.326. **Match the house style:** the project's docstring format, tone, and33 density. A file where every second line is commented reads as noise;34 one comment on the genuinely surprising line reads as a flare.3536## What not to write3738- Restatements: "increment i by one".39- Changelogs in comments: version control already remembers.40- Commented-out code: delete it; the attic is git.41- Apologies without information: "hack, sorry" helps nobody, while42 "workaround for framework issue #4182, removable at v3" is a plan.4344## Litmus test4546Cover the code and read only the comments and names: do you know what this47module is for, what its edges are, and what you must not break? Then cover48the comments: does anything in the code surprise you that a comment should49have flagged?
Amey-Thakur