Documentation — inline comments, docstrings, README, ADRs: Visual walkthrough

Prerequisites we'll lean on: Self-documenting Code, Clean Code & Naming, API Design & Contracts, Onboarding & Bus Factor. This page is a child of the Documentation topic note.

Step 1 — The one number everything rests on: the read/write ratio

WHAT we did: we named the single quantity the whole argument hangs on. $R$ is "how many times a future human looks at this code"; $W$ is "how many times someone types it". The ratio $\frac{R}{W}$ is a pure number (no units) — it just says reads happen many times more often than writes.

WHY this tool and not another: we need a ratio, not a raw count, because we're about to compare two costs (writing docs vs re-reading code). A ratio is exactly the tool that lets a small per-read cost get multiplied into something large. That multiplication is the entire argument.

PICTURE (figure s01): the black bar is the one time you write a line; the red bar is the pile of times it gets read afterward. The red dwarfs the black — that lopsidedness is the seed of everything below.

Figure — Documentation — inline comments, docstrings, README, ADRs

Step 2 — Turning the ratio into money: the amortization inequality

WHAT each symbol is doing:

$c_{w}$ — a one-time cost. You pay it the moment you type the comment. It sits alone on the left.
$s$ — the per-read saving. Tiny per read (maybe you save 4 seconds of head-scratching).
$R$ — the multiplier. This is the read count from Step 1. It turns the tiny $s$ into a big total.
$s \cdot R$ — total saving across the code's life. The dot $\cdot$ (just defined) means multiply: " $s$ , added up $R$ times".

WHY this tool: an inequality is the right instrument because a decision ("write the doc or not?") is a threshold question — is the benefit past the break-even line or not? The inequality draws that line explicitly.

WHY it almost always holds: from Step 1, $R > 1$ (usually many times larger). Even if $s$ is small, a large $R$ blows up the right side past $c_{w}$ . This is called amortization: pay once, save many times.

PICTURE (figure s02): two lines vs the number of reads. The flat black line is $c_{w}$ — it never grows. The rising red line is $s \cdot R$ — it climbs with every read. They cross exactly at $R^{⋆} = c_{w} / s$ (the red dot); after that, docs are pure profit.

Recall

Why does documentation "pay for itself"? ::: You pay $c_{w}$ once, but save $s$ on each of $R$ reads; since $R > 1$ , $s \cdot R$ eventually overtakes $c_{w}$ — that crossing point is break-even. What is $R^{⋆}$ and how do you compute it? ::: The break-even read count $R^{⋆} = c_{w} / s$ : the number of future reads at which a doc exactly pays for itself. Write the doc if you expect more reads than $R^{⋆}$ .

Step 3 — Zooming out: one line vs a whole project (the scope axis)

WHAT we did: we noticed a hidden variable — scope — that the flat inequality ignored. A one-line quirk has a tiny reader pool (whoever edits that block). A whole project has a huge reader pool (every newcomer on the internet). Same economics, different zoom level.

WHY this tool: think of scope as a horizontal axis running from "one line" (left) to "whole project" (right). Plotting audience size against scope reveals why one form of doc can't do it all — a comment buried in line 812 is useless to a stranger deciding whether to install your library.

PICTURE (figure s03): a horizontal zoom axis. As the red bracket widens from a single line to the whole repo, the stick-figure crowd (audience) grows. Marked positions on this axis will become our layers in Step 4.

Step 4 — The layers fall out of the axis (a spectrum, not exactly four)

Intuition Scopes map to documents (a continuum with named landmarks)

There is no algebra here — this is a taxonomy read off the scope axis. Each position on the axis has a document that fits its audience and its question:

Scope (left → right)	Document	Question it answers
line / block	inline comment	WHY this line?
function / class	docstring	HOW do I use this?
one subsystem	architecture overview	HOW do the parts fit?
contributor workflow	CONTRIBUTING guide	HOW do I help?
whole project	README	WHAT is it? how to start?
one decision	ADR	WHY chosen over Y?

WHAT this table is doing: the left column is a position on the scope axis from Step 3; the middle is the document that lives at that scope (all six now defined — the two less-familiar ones in the callout just above); the right is the one question it answers.

WHY the parent's "four layers" are landmarks, not a complete list: the four canonical layers (inline → docstring → README → ADR) are the most common landmarks, which is why the mnemonic below uses them. But the axis is a continuum: real projects grow intermediate artifacts — a CONTRIBUTING guide (scope: contributor workflow) or an architecture overview (scope: one subsystem), both defined above. Each still obeys the same amortization economics; it just sits at a different point on the axis. Don't treat "four" as a hard ceiling — treat it as the four you'll meet first.

WHY each landmark maps to the inequality: each minimizes a different re-reading cost — inline comments cut the cost of re-guessing intent, docstrings cut the cost of reading the body (see API Design & Contracts), READMEs and CONTRIBUTING guides cut onboarding cost (see Onboarding & Bus Factor), ADRs cut re-debate cost.

PICTURE (figure s04): the zoom axis from Step 3, now with the documents stacked at their scope positions, each tagged with its one question. This is the parent note's table — but derived, not asserted, with the two intermediate landmarks (architecture overview, CONTRIBUTING) shown as fainter marks between the four canonical ones.

Step 4½ — The honest inequality: writing is not the only cost

WHAT we did: we corrected Step 2's simplest form, which pretended a doc is written once and frozen. That's true for an ADR (immutable by design → $m \approx 0$ ) but false for a docstring or README, which must track the code. We added the term $m$ to the cost side so the model covers all layers, not just comments.

WHY this matters per layer — costs are NOT uniform across the axis:

ADR: $m \approx 0$ (immutable, dated, append-only), $s$ large and durable (context never re-evaporates once written). Almost always worth it.
Docstring: small $c_{w}$ , small-to-moderate $m$ (must follow signature changes), large $s$ amplified because tools re-serve it (Step 7). Usually worth it.
README: moderate $c_{w}$ , higher $m$ (drifts as install steps change), enormous $R$ (every visitor). Worth it, but keep it short so $m$ stays low.
Inline WHAT-comment: $s \approx 0$ , $m > 0$ → the whole left side beats the right → negative value (this is Step 5's edge case).

WHY the analysis isn't static: both $s$ and $m$ decay or grow over time. A README's per-read saving $s$ shrinks if the tool becomes obvious; a docstring's $m$ spikes right after a big refactor. The rule that survives all this is simple and robust: minimize $m$ (keep docs short, put durable facts in immutable ADRs, and push everything you can into self-documenting code where $m$ is paid by the code itself).

PICTURE (figure s05): the Step 2 chart, now with the cost line lifted from a flat $c_{w}$ to a gently rising $c_{w} + m$ (upkeep accrues over time), and the break-even read $R^{⋆}$ pushed rightward.

Step 5 — Edge case A: when a comment has negative value

WHAT we did: we plugged the worst case into the upgraded inequality from Step 4½. A redundant comment (i = i + 1 # increment i) tells the reader nothing new, so $s \approx 0$ , while its maintenance penalty $m$ (defined in Step 4½) stays positive.

WHY this matters: with $s \approx 0$ and $m > 0$ , the condition $c_{w} + m < s \cdot R$ becomes $c_{w} + m < 0$ — impossible, since costs are positive. Equivalently the break-even $R^{⋆} = (c_{w} + m) / s$ blows up toward infinity as $s \to 0$ : no number of reads can ever pay it off. The comment's net value $s \cdot R - c_{w} - m$ is negative — the comment is worse than nothing. This is exactly why the parent rule is "comments say WHY, never WHAT": WHY-comments encode external knowledge the code can't show (an incident number, a vendor quirk), giving a large, durable $s$ . Restating WHAT gives $s \approx 0$ .

WHY the fix is renaming, not commenting: if a comment could be dissolved by a better name or a smaller function, do that — see Self-documenting Code and Clean Code & Naming. Then $s$ lives inside the code and can never go stale (the code is the doc, so $m$ is paid by tests and the compiler, not by a human's memory).

PICTURE (figure s06): two paths of the same code over time. Top: a WHY-comment ( $s$ stays high, red line holds). Bottom: a WHAT-comment ( $s \approx 0$ , and after an edit the comment turns red-crossed = a lie). The bottom path dips below zero.

Step 6 — Edge case B: the degenerate project (bus factor = 1)

WHAT we did: we pushed the scenario to a degenerate extreme — a project where a key decision was never written down, and the one person who knew it is gone.

WHY this is the strongest case for ADRs — mapped straight into the inequality: plug the bus-factor-1 scenario into $c_{w} + m < s \cdot R$ term by term:

$R$ (reads): every future "why did we choose X?" question is one read. With no ADR, each such question does not cost a cheap re-read — it triggers a full re-discovery from scratch. So the effective per-question cost, i.e. the saving $s$ an ADR would provide, is huge.
$s$ (saving per read): with the one knower gone, the alternative to reading an ADR is re-debating the whole decision, possibly for hours, possibly never resolving it. So $s$ isn't "4 seconds" — it can be hours per question, the largest $s$ anywhere on the page.
$m$ (upkeep): an ADR is immutable and dated, so it never needs updating → $m \approx 0$ .
Verdict: the right side $s \cdot R$ is enormous and the left side $c_{w} + m \approx c_{w}$ (a 15-minute write) is tiny. The inequality $c_{w} + m < s \cdot R$ holds by a landslide — equivalently $R^{⋆} = (c_{w} + m) / s$ is tiny (well under one question), so the ADR pays off on its very first reuse. Bus factor 1 is the case where documentation's return is largest.

PICTURE (figure s07): two teams facing the same "why Postgres?" question a year later. Black team (no ADR, bus factor 1): tangled arrows, dead-ends, the lone knower already gone → red question mark stays unanswered (each read = costly re-discovery, large $s$ ). Red-doc team: one immutable ADR node ( $m \approx 0$ ) answers instantly.

Step 7 — Why docstrings sit apart: machine-readable, not just human-readable

WHAT we did: we split the layers along a second axis — machine-accessibility. Inline comments and prose live only for human eyes. A docstring, being a real string object, is extractable by programs.

WHY this multiplies the saving $s$ : because one docstring can be served through many channels at once — the IDE tooltip that pops up as you type, the auto-generated API website (Sphinx reads obj.__doc__), and the interactive help(obj) console. Each channel is an independent stream of reads. In the amortization inequality that means the same one-time cost $c_{w}$ is divided across several large read counts $R_{1} + R_{2} + R_{3}$ , while $m$ stays fixed. So a docstring's effective $s \cdot R$ is turbocharged relative to a plain comment — you write once and the machine re-delivers it everywhere, forever, for free.

WHY it matters for the contract: because the docstring states the contract — preconditions (Args), the postcondition (Returns), and failure modes (Raises); see API Design & Contracts — a caller can use the function without ever opening its body. Skipping the body is a large per-read saving $s$ , which is why the docstring is the highest-value doc at inline scope. This is the answer to "why docstrings sit apart": they are the only inline-scope doc that is both a human-readable contract and machine-extractable, so they collect the biggest $s$ and the widest $R$ of anything living next to the code.

PICTURE (figure s08): one docstring in the center; three red arrows fan out to an IDE tooltip, a Sphinx-generated doc page, and a help() console — three read-streams from one write. A plain comment sits alone with a struck-through arrow — it reaches no tool.

The one-picture summary

Everything above is one story: one lopsided fact (reads outnumber writes, $R > 1$ ) forces one inequality ( $c_{w} + m < s \cdot R$ ) with a single decision boundary — the break-even read count $R^{⋆} = (c_{w} + m) / s$ — which, read along a scope axis, splits into a spectrum of documents (inline → docstring → … → ADR), with edge cases (stale comments, bus-factor-1, machine-extractable docstrings) each sharpening which document to reach for — and the durable rule being keep the maintenance penalty $m$ small.

Recall Feynman retelling — the whole walkthrough in plain words

Imagine you write a note on a page once, but many kids will read it later. Even if your note saves each kid just a few seconds, lots of kids × a few seconds beats the minute you spent writing it. There's even a magic number, $R^{⋆}$ : the number of readers you need before the note has paid for itself. Below it, don't bother; above it, always write the note (Steps 1 & 2).

But there's a catch: some notes have to be kept up to date. If you change the castle, you must re-check the note — that's an ongoing cost (Step 4½), and it raises the magic number, so you need even more readers to make it worthwhile. A note you never have to touch (like a diary entry about a past decision) is the cheapest to keep; a poster at the gate that keeps changing costs more upkeep. So: keep notes short, and prefer notes you never have to edit.

Now, who reads it changes with how much you're talking about. A note about one tricky brick is for whoever fixes that brick — a sticky note (inline comment). A note about how to use a whole tower is for players — a card on the tower (docstring). There are in-between notes too — a "how the towers connect" map (architecture overview) and a "how to help build" note (CONTRIBUTING). A note about the whole castle is for newcomers at the gate — a poster (README). And a note about why we made the moat blue not red is a diary entry so nobody repaints it red next year (ADR). Same idea, many zoom levels (Steps 3 & 4).

Two warnings. A sticky note that just says "this is a brick" is useless and, worse, might turn into a lie when you change the brick — its magic number is infinity, so it can never pay off (Step 5). And if only one kid knows why the moat is blue and that kid goes home, the secret is lost forever — that's why the diary (ADR) is worth the most: each question would otherwise cost hours, so it pays off on the very first ask (Step 6). Finally, the tower-cards are special: a robot can read them out loud to everyone automatically — one card, many readers — so they pull double duty (Step 7). That's the entire castle of documentation, built from one number.