Documentation — inline comments, docstrings, README, ADRs

WHY documentation exists at all

WHY it matters (the economics): Code is read far more often than it is written — studies and folklore put the ratio around 10:1 reads to writes. Even a tiny per-read saving multiplied by hundreds of reads dwarfs the writing cost. Documentation is amortized: write once, save on every future read.

WHAT goes wrong without it: "bus factor" of 1 (only one person understands a module), decisions re-litigated endlessly, onboarding measured in weeks, and bugs from people guessing intent.

The four layers (each answers a different question, at a different scope)

Layer	Scope	Audience	Question it answers	Lives where
Inline comment	a line / block	code maintainer	Why this surprising line?	in the code
Docstring	a function / class / module	API caller	How do I use this?	attached to the object
README	the whole project	new user/dev	What is this & how do I start?	repo root
ADR	one decision	future architects	Why did we choose X over Y?	`docs/adr/`

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

1. Inline comments — explain the why, never the what

HOW to decide if a comment earns its place — ask: "Could I rewrite the code so this comment becomes unnecessary?" If yes, rename a variable / extract a function instead. Comments that restate code rot, because the code changes and the comment silently lies.

Worked example Good vs bad inline comment

# BAD — restates the code (says WHAT, adds nothing)
i = i + 1   # increment i
 
# GOOD — explains the WHY the code cannot show
# Retry up to 3×: the payment gateway returns spurious 503s under load (see INC-4821)
for _ in range(3):
    ...

Why this step? The good comment encodes external knowledge (a real incident, a vendor quirk) that is invisible in the code. That is exactly what code can't self-document.

2. Docstrings — the contract of a function

WHY attached, not just a comment: because it's a real string object, tools can extract it — IDE tooltips, help(), auto-generated API docs (Sphinx). A comment is invisible to these; a docstring is machine-accessible documentation.

Worked example A docstring as a contract

def withdraw(balance: float, amount: float) -> float:
    """Subtract amount from balance and return the new balance.
 
    Args:
        balance: current funds, must be >= 0.
        amount:  amount to remove, must be > 0 and <= balance.
    Returns:
        The new balance (balance - amount).
    Raises:
        ValueError: if amount <= 0 or amount > balance.
    """
    if amount <= 0 or amount > balance:
        raise ValueError("invalid amount")
    return balance - amount

Why this step? Each section answers a caller's question without reading the body: preconditions (Args), postcondition (Returns), failure modes (Raises). That is the API contract — Feynman-style, you've explained the function so well the reader never opens it.

3. README — the front door

HOW to structure it (highest-value-first, the 80/20 of docs):

One-sentence what + why (the 20% read by 80% of visitors)
Install (copy-pasteable commands)
Quickstart / minimal example
Usage / config
Contributing & License

Worked example Skeleton README

# PayKit
Lightweight retry-safe payment client for the Acme gateway.
 
## Install
pip install paykit
 
## Quickstart
from paykit import charge
charge(amount=10.00, currency="USD")

Why this step? The first 5 lines let a stranger decide "is this for me?" and run something. If they must read 300 lines to run one command, most leave.

4. ADR — Architecture Decision Record

WHY ADRs (the killer feature): code shows the current state but erases history. Six months later someone asks "why are we using Postgres not Mongo?" — without an ADR they re-debate from zero. An ADR is the memory of why a decision was made, including the rejected options (Steel-man: records why the alternative felt right and why it lost).

Worked example Minimal ADR

# ADR-007: Use PostgreSQL for primary store
Date: 2024-03-11   Status: Accepted
 
## Context
We need ACID transactions for balances; data is highly relational.
 
## Decision
Use PostgreSQL.
 
## Alternatives considered
- MongoDB: faster prototyping, but no multi-document ACID at the time → rejected.
 
## Consequences
+ Strong consistency, mature tooling.
− Team must learn SQL migrations; heavier ops than a managed doc store.

Why this step? Status + Date make it immutable history; Alternatives + Consequences stop the same debate recurring. You never edit ADR-007; you write ADR-015 that supersedes it.

Recall Feynman: explain it to a 12-year-old (hidden — recall first!)

Imagine you build an awesome LEGO castle. The bricks are your code.

A sticky note on a tricky brick saying "this bit holds the gate, don't pull it" = inline comment.
A little card on each tower saying "to open this tower, twist the flag" = docstring.
A poster at the entrance: "This is Dragon Castle! Here's how to play." = README.
A diary entry: "We made the moat blue, not red, because red paint kept dripping." = ADR. The castle still works without any of these — but the next kid who plays (or future-you who forgot) will be lost and break things. Notes turn a mystery box into a friendly guide.

Flashcards

What single question should an inline comment answer?

Why (the rationale/intent the code can't express) — never what the code already shows.

Why prefer renaming/extracting over adding a comment?

Self-documenting code can't rot; comments can drift out of sync and start lying when code changes.

What makes a docstring different from a comment, technically?

A docstring is a real string object attached to the code object (__doc__), so tools like help(), IDEs, and Sphinx can extract it; comments are invisible to those tools.

Name the three contract parts a function docstring should cover.

Preconditions (Args), postcondition (Returns), and failure modes (Raises).

What is the 80/20 of a README's top section?

A one-sentence what + why plus copy-pasteable install/quickstart — the small part most visitors read to decide and run something.

What does an ADR record that code cannot?

The why behind a decision, including alternatives considered and their consequences — the history code erases.

Why are ADRs immutable and dated?

They are an append-only historical log; you don't edit a past decision, you write a new ADR that supersedes it, preserving the timeline.

What is the read:write ratio that justifies documentation?

Roughly 10:1 — code is read far more than written, so per-read savings amortize the writing cost.

Steel-man "more comments = better": why is it wrong?

Redundant comments add maintenance surface and risk becoming stale/lying; quality (why-comments) beats quantity.

Match scope→artifact: a single surprising line / a function / a project / a decision.

inline comment / docstring / README / ADR.

Connections

Clean Code & Naming — good names reduce the need for inline comments.
Self-documenting Code — the alternative-first principle behind "explain why, not what".
API Design & Contracts — docstrings formalize the function contract.
Sphinx & Doc Generation — tooling that consumes docstrings.
Architecture & System Design — ADRs are the decision log of this.
Onboarding & Bus Factor — the problem documentation directly mitigates.
Markdown — the format of READMEs and ADRs.

Concept Map

Hinglish (regional understanding)

Intuition Hinglish mein samjho

Dekho, code do logon ke liye likha jaata hai: ek computer ke liye (woh batata hai kya karna hai), aur ek insaan ke liye (jo baad mein isko padhega aur change karega). Documentation us doosre insaan ke liye hai — aksar woh "future-you" hi hota hai jo 6 mahine baad apna hi code dekh ke confuse ho jaata hai! Yaad rakho: code kaise batata hai, documentation kyun batata hai. Aur kyunki code ek baar likha jaata hai par baar-baar (kareeb 10 guna zyada) padha jaata hai, thodi mehnat ab karke aage har baar time bachta hai — yeh ek smart investment hai.

Char layers hote hain, ek zoom ladder ki tarah. Inline comment ek line ke baju mein hota hai aur sirf why batao — jaise "yahan 3 baar retry kar rahe hain kyunki gateway 503 deta hai (INC-4821)". Kabhi what mat likho jaise i = i + 1 # i ko badhao — woh bekaar hai aur jab code badle to comment jhooth bolne lagta hai. Docstring function ke andar pehli string hoti hai jo uska contract batati hai: Args, Returns, Raises — taaki caller body padhe bina samajh jaaye. Yeh tool-friendly hai, help() aur IDE isse padh sakte hain.

README project ka front door hai — pehli line mein "yeh kya hai aur kyun", phir copy-paste karne laayak install aur quickstart. Most log sirf upar ka 20% padh ke decide karte hain, isliye sabse zaroori cheez upar rakho (yeh 80/20 rule hai). ADR (Architecture Decision Record) ek dated, immutable note hai jo batata hai ki humne ek bada decision kyun liya — jaise "Postgres chuna, Mongo nahi, kyunki ACID chahiye tha". Code current state dikhata hai par history mita deta hai; ADR woh history bachata hai taaki 6 mahine baad wahi bahas dobara na ho. 15 minute lagao jab context fresh hai — baad mein ghante bachenge.

Documentation — inline comments, docstrings, README, ADRs

WHY documentation exists at all

The four layers (each answers a different question, at a different scope)

1. Inline comments — explain the why, never the what

2. Docstrings — the contract of a function

3. README — the front door

4. ADR — Architecture Decision Record

Flashcards

Connections

Concept Map

Hinglish (regional understanding)

Go deeper — visual, from zero

Test yourself — Software Engineering

Connections