Code documentation

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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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?