code-documentationlisted

# 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 fo