Key Takeaways — Chapter 24: Code Documentation

The summary card. Read this to re-ground before the quiz, before Chapter 25, or before documenting anything.

The one idea

The code already says what it does; documentation exists to capture what the code cannot say — the why. A comment that restates the code (# increment i) carries no information, exactly like "it is important to note that" in prose. A comment that captures a reason — intent, a constraint, a decision, a workaround — carries the one thing a future reader can't recover from the code. Comment the why, not the what. That's the whole chapter.

🚪 Threshold concept: Before, you think a comment's job is to explain the code, so more comments feel like better documentation. After, you see the code explains itself; a comment's job is to record what the code can't express. Cross that line and redundant comments read as clutter, while a missing why on a non-obvious line reads as a gap. You stop asking "does this describe the code?" and start asking "does this tell me something the code can't?"

Your first reader

You, six months from now — with none of the context you hold while writing — and the next maintainer right behind you. Both arrive as strangers to the code. Documentation is a letter to your future, confused self: write the note that would have saved you the re-derivation. "Only I will touch it" doesn't mean "no docs needed"; it means future-you needs them, and future-you knows nothing present-you knows.

The four layers (each documents what the layer below can't)

• A comment is internal (the why of a line, for the implementer). A docstring is external (the interface, for a caller who won't read the body). Don't swap them.
• Type hints document the what of the data, never the why. base: datetime | None says what base is; it can't say why it defaults to now.
• A good docstring lets a caller use the function correctly from the docstring alone.

Self-documenting code

Good names and structure make the what self-evident — which is what frees comments to do their real job, the why. - An intention-revealing name (days_until_expiry, not d) is a comment that's read everywhere the value is used and can't drift. Chapter 7's word-choice skill, applied to identifiers. - Name your magic numbers (RENEWAL_REMINDER_THRESHOLD_DAYS, not 7). Extract well-named functions so the calling code reads like the comment you were about to write. - "Self-documenting" never means "no comments." It means no redundant comments — the what vanishes into the code so the why can stay in a comment, where it's irreplaceable.

The documentation spectrum

None → Too much → Right. - None is a maze: every why re-derived (the more common, more obvious failure). - Too much is the sneaky failure dressed as diligence: noise buries the real whys, comments rot into lies, and the obvious gets narrated while the subtle gets skipped. - A stale comment is worse than no comment — no comment makes you read the (true) code; a wrong comment makes you trust a falsehood. Change comments in the same edit as the code; prefer documentation that can't drift. - The center is judgment: every why captured, every what left to the code, nothing narrated. Comment density doesn't measure quality — well-documented code is usually sparse with comments, each load-bearing.

If you remember three things

1. Comment the why, not the what — the code carries the what; only a comment can carry the why.
2. Document for future-you — the guaranteed reader who's lost all the context.
3. More is not better; calibrated is better — and a stale comment is worse than none.

Themes surfaced: #1 writing-is-thinking (articulating a why in a comment forces you to have the why — and can surface a bug, as in Case Study 1) · #3 clarity-is-not-the-enemy-of-precision (cut the narration, keep the reason — same as cutting fog in Ch 3) · #7 the-best-writing-is-invisible (good docs let the reader see the intent, not the prose) · #6 every-sentence-earns-its-place (every comment must carry a why) · #2 audience-is-everything (the caller reads the docstring; the implementer reads the comment).

Threshold concept: The code says what it does; documentation captures what the code cannot say.

Back to: Chapter 24 · Exercises · Quiz · Further Reading