Documentation — inline comments, docstrings, README, ADRs

4.5.21 · Coding › Software Engineering

WHY documentation exist hi kyun karti hai

WHY yeh matter karta hai (the economics): Code likhne se kahin zyada baar padha jaata hai — studies aur folklore is ratio ko 10:1 reads to writes ke aas paas rakhte hain. Ek tiny per-read saving ko sau reads se multiply karo toh woh writing cost se kahin zyada ho jaata hai. Documentation amortized hai: ek baar likho, har future read par bachao.

WHAT galat hota hai bina iske: "bus factor" of 1 (sirf ek hi insaan ek module samajhta hai), decisions baar baar litigate hote hain, onboarding weeks mein measure hoti hai, aur bugs tab aate hain jab log intent guess karte hain.

Char layers (har ek alag sawaal ka jawab deta hai, alag scope par)

Layer	Scope	Audience	Sawaal jo yeh answer karta hai	Kahan rehta hai
Inline comment	ek line / block	code maintainer	Yeh surprising line kyun?	code mein
Docstring	ek function / class / module	API caller	Main isse kaise use karun?	object ke saath attached
README	poora project	naya user/dev	Yeh kya hai aur main kaise shuru karun?	repo root mein
ADR	ek decision	future architects	Humne Y ke upar X kyun choose kiya?	`docs/adr/` mein

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

1. Inline comments — why explain karo, kabhi what nahi

HOW decide karo ki comment apni jagah earn karta hai ya nahi — poochho: "Kya main code ko rewrite kar sakta hoon taaki yeh comment unnecessary ho jaaye?" Agar haan, toh variable rename karo / function extract karo. Jo comments code ko restate karte hain woh rot karte hain, kyunki code change hota hai aur comment chup chap jhooth bolta rehta hai.

Worked example Acha vs bura inline comment

# BAD — code ko restate karta hai (WHAT kehta hai, kuch add nahi karta)
i = i + 1   # increment i
 
# GOOD — WHY explain karta hai jo code show nahi kar sakta
# Retry up to 3×: payment gateway load ke neeche spurious 503s return karta hai (dekho INC-4821)
for _ in range(3):
    ...

Yeh step kyun? Accha comment external knowledge encode karta hai (ek real incident, ek vendor quirk) jo code mein invisible hai. Yahi woh cheez hai jo code khud document nahi kar sakta.

2. Docstrings — ek function ka contract

WHY attached, sirf comment nahi: kyunki yeh ek real string object hai, tools isse extract kar sakte hain — IDE tooltips, help(), auto-generated API docs (Sphinx). Comment in sab ke liye invisible hai; docstring machine-accessible documentation hai.

Worked example Ek 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

Yeh step kyun? Har section caller ka sawaal body padhe bina answer karta hai: preconditions (Args), postcondition (Returns), failure modes (Raises). Yahi API contract hai — Feynman-style, tumne function ko itna achhi tarah explain kar diya ki reader isse kabhi kholega hi nahi.

3. README — front door

HOW isko structure karo (highest-value-first, docs ka 80/20):

Ek-sentence what + why (20% jo 80% visitors padhte hain)
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")

Yeh step kyun? Pehli 5 lines ek stranger ko decide karne deti hain "kya yeh mere kaam ka hai?" aur kuch run karne deti hain. Agar unhein ek command run karne ke liye 300 lines padhni padein, toh zyada log chale jaate hain.

4. ADR — Architecture Decision Record

WHY ADRs (killer feature): code current state dikhata hai lekin history erase kar deta hai. Chhe mahine baad koi poochh ta hai "hum Postgres kyun use kar rahe hain, Mongo kyun nahi?" — bina ADR ke woh zero se re-debate karte hain. ADR yeh why ki memory hai ki ek decision kyun liya gaya, rejected options samait (Steel-man: record karta hai kyun alternative sahi laga aur kyun haara).

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.

Yeh step kyun? Status + Date isse immutable history banate hain; Alternatives + Consequences wohi debate dobara hone se rokते hain. Tum kabhi ADR-007 edit nahi karte; tum ADR-015 likhte ho jo isse supersede karta hai.

Recall Feynman: ek 12-saal ke bachche ko explain karo (hidden — pehle recall karo!)

Socho tumne ek awesome LEGO castle banaya. Bricks tumhara code hain.

Ek tricky brick par sticky note jo kahe "yeh hissa gate ko thaame hai, isko mat khiincho" = inline comment.
Har tower par ek chhota card jo kahe "is tower ko kholne ke liye flag ghoomao" = docstring.
Entrance par ek poster: "Yeh Dragon Castle hai! Khelne ka tarika yeh hai." = README.
Ek diary entry: "Humne khai ko laal ki jagah blue banaya, kyunki laal rang tapakta rehta tha." = ADR. Castle bina in sab ke bhi kaam karta hai — lekin agla bachcha jo khele (ya future-you jo bhool gaya) kho jaayega aur cheezein torega. Notes ek mystery box ko friendly guide mein badal dete hain.

Flashcards

Ek inline comment ko konsa ek sawaal answer karna chahiye?

Why (rationale/intent jo code express nahi kar sakta) — kabhi what nahi jo code already dikhata hai.

Comment add karne ki jagah rename/extract kyun prefer karein?

Self-documenting code rot nahi kar sakta; comments drift ho sakte hain aur jab code change ho toh jhooth bolne lagte hain.

Kya cheez technically docstring ko comment se alag banati hai?

Docstring ek real string object hai jo code object se attached hoti hai (__doc__), isliye help(), IDEs, aur Sphinx jaisi tools isse extract kar sakti hain; comments un tools ke liye invisible hain.

Ek function docstring ke teen contract parts ke naam batao.

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

README ke top section ka 80/20 kya hai?

Ek-sentence what + why plus copy-pasteable install/quickstart — woh chhota hissa jo zyaatar visitors padhte hain decide karne aur kuch run karne ke liye.

ADR kya record karta hai jo code nahi kar sakta?

Ek decision ke peeche ka why, jisme consider kiye gaye alternatives aur unke consequences shamil hain — woh history jo code erase kar deta hai.

ADRs immutable aur dated kyun hote hain?

Yeh ek append-only historical log hain; tum past decision edit nahi karte, tum ek naya ADR likhte ho jo isse supersede karta hai, timeline preserve karte hue.

Documentation ko justify karne wala read:write ratio kya hai?

Roughly 10:1 — code likhne se kahin zyada baar padha jaata hai, isliye per-read savings writing cost ko amortize kar deti hain.

Steel-man "zyada comments = better": kyun galat hai?

Redundant comments maintenance surface add karte hain aur stale/jhooth bolne wale banne ka risk rakhte hain; quality (why-comments) quantity se better hai.

Scope→artifact match karo: ek single surprising line / ek function / ek project / ek decision.

inline comment / docstring / README / ADR.

Connections

Clean Code & Naming — achhe names inline comments ki zaroorat kam karte hain.
Self-documenting Code — "explain why, not what" ke peeche alternative-first principle.
API Design & Contracts — docstrings function contract ko formalize karte hain.
Sphinx & Doc Generation — tooling jo docstrings consume karta hai.
Architecture & System Design — ADRs iski decision log hain.
Onboarding & Bus Factor — woh problem jo documentation directly mitigate karta hai.
Markdown — READMEs aur ADRs ka format.