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?