Documentation — inline comments, docstrings, README, ADRs: Question bank

The four layers this bank drills, from narrowest to widest scope:

True or false — justify

Every answer below must survive the "so what?" test — a bare true/false earns nothing.

True or false: "Well-commented code is a sign of high-quality code."

False. Comment volume is not quality; the best code is often self-documenting and needs few comments. Redundant comments add maintenance surface that can silently rot into lies.

True or false: A docstring and an inline comment are basically the same thing in a different spot.

False. A docstring is a real string object attached to a function/class — tools like help(), IDEs, and Sphinx can extract it. A comment is invisible to those tools and serves a different audience (the maintainer, not the caller).

True or false: If you edit a function's behaviour, the compiler will warn you that its docstring is now stale.

False. Documentation is invisible to the compiler; nothing checks that prose matches code. Stale docs are a human failure that only reviews and tests catch, which is why lying comments are worse than none.

True or false: You should update ADR-007 when the decision it records turns out to be wrong.

False. ADRs are immutable, dated history. You never edit ADR-007; you write a new ADR (e.g. ADR-015) that supersedes it, preserving the record of what you once believed and why.

True or false: A good README should document every configuration option and edge case up front.

False. A README is highest-value-first: what/why in one sentence, then install, then a runnable quickstart. Exhaustive detail belongs in API docs — burying "run this" under 300 lines makes strangers leave.

True or false: "The code is the documentation" — so if code is clean enough, you need no other docs.

False. Clean code shows the current how; it cannot show why (an incident, a vendor quirk) or history (rejected alternatives). Code erases the reasoning behind it — that's exactly what comments and ADRs preserve.

True or false: The primary reader of your documentation is the computer running your program.

False. The compiler never reads comments or docstrings-as-prose. The reader is always the next human — often future-you — so you optimize for human understanding, not machine execution.

True or false: Documentation costs more than it saves because writing it takes time now.

False. It is amortized: code is read roughly 10× more than written, so a tiny per-read saving multiplied across hundreds of reads dwarfs the one-time writing cost.

Spot the error

Each item contains a real mistake — name what is wrong and why.

What's wrong: i = i + 1 # increment i

The comment restates the code (says what), adding zero information while creating a lie-risk if the line later changes. A comment should carry why knowledge the code can't express, not narrate the obvious.

What's wrong: """Withdraws money.""" as the docstring for def withdraw(...).

It just echoes the function name and hides the contract. It omits parameter bounds, units, the return value, and what it raises — the very things a caller needs to avoid reading the body.

What's wrong: An ADR titled "ADR: Database choice" with no date and no status line.

Without Date and Status, it can't function as immutable history — you can't tell if it's Proposed, Accepted, or Superseded, nor when the context applied. Those fields are what make an ADR a memory instead of a mutable opinion.

What's wrong: A README whose first section is a 40-line "History and Motivation" essay before any install command.

It violates highest-value-first ordering. The 80% of visitors deciding "is this for me?" need the one-line what/why and a runnable command first; motivation prose can wait or move to an architecture doc.

What's wrong: A comment reading # TODO: this is slow, fix later left in the code for two years with no linked issue.

A rationale-free, untracked TODO becomes noise nobody acts on. A useful warning-style comment links to an issue (see INC-4821) so the why and the follow-up are recoverable.

What's wrong: An ADR that lists only the chosen option and never mentions what was rejected.

Its killer feature is missing. Without the alternatives considered and why they lost, the same debate re-opens in six months — the ADR fails to prevent re-litigation.

Why questions

Why is a lying comment considered worse than having no comment at all?

A missing comment forces you to read the code (slow but truthful); a lying comment actively misleads you into a wrong mental model, causing bugs while looking authoritative. Trust in one stale comment poisons trust in all of them.

Why do we attach a docstring to the object instead of writing a comment above the function?

Because a docstring is a live string retrievable at runtime (obj.__doc__, help()) and extractable by doc generators and IDEs. This makes it machine-accessible — comments are invisible to all those tools.

Why does an ADR record the strongest version of the rejected option ("steel-man"), not a strawman?

Recording why the alternative genuinely felt right proves the decision was made with eyes open, and lets a future reader re-evaluate honestly if circumstances change. A strawman fools no one and invites re-debate.

Why does the parent note say documentation answers why while code answers how?

The how is mechanically visible in the instructions; the why — intent, trade-offs, external context — lives only in the author's head and vanishes when they leave. Docs capture the part the code physically cannot express.

Why is a "bus factor of 1" a documentation problem and not just a staffing problem?

If only one person understands a module because the why was never written down, losing them ("hit by a bus") loses irrecoverable knowledge. Documentation raises the bus factor by externalizing understanding.

Why should you write an ADR while the context is still hot rather than later?

The reasoning feels obvious today, so the temptation is to skip it — but context evaporates as people and priorities shift. Fifteen minutes now prevents hours of rediscovery in six months.

Edge cases

A function's name and types make its behaviour totally obvious. Does it still need a docstring?

If the contract is genuinely fully expressed by the signature, a minimal or absent docstring is fine — but the moment there are hidden preconditions, units, side-effects, or raised errors, those must be documented because they aren't visible in the signature.

Your repo has zero surprising lines, perfectly clear names — how many inline comments should it have?

Possibly zero. Inline comments earn their place only for the non-obvious why (a vendor quirk, an incident link, a # WARNING: not thread-safe); clean naming rightly eliminates the rest.

You made a tiny, reversible decision (which JSON library to use). Does it deserve an ADR?

Usually no. ADRs are for significant decisions with lasting consequences and real alternatives; documenting trivial, easily-reversed choices clutters the log and dilutes the signal of the ones that matter.

A decision was superseded — should you delete the old ADR to avoid confusion?

No. You mark its status "Superseded by ADR-XXX" and leave it in place. The append-only log's value is that it shows the evolution of thinking; deleting history is exactly what an ADR exists to prevent.

Your project is a private one-file script only you will ever touch. Is any documentation worth it?

Even then, "future-you" is a different person who forgot the context — a one-line header on the why and any gotcha still pays off. The break-even simply arrives later than on a shared project.

The README quickstart command works, but a subtle config flag is needed in production. Where does that flag go?

Not in the quickstart (which stays minimal and runnable) but in a later Usage / Config section, so the first-run path stays frictionless while production users can still find the detail. See Markdown for structuring those sections.

Recall One-line self-test before you leave

For any doc you write, can you name (a) its audience, (b) the question it answers, and (c) whether the info is invisible in the code? If any answer is fuzzy, the doc is probably redundant or misplaced. See the parent Documentation note for the four-layer ladder.