Further Reading — Chapter 24: Code Documentation

Annotated, Tier 1 and Tier 2 sources only (real, verifiable works and conventions — no invented citations). Start with the conventions; the books deepen the judgment.

Tier 1 — The conventions (read these first; they're short and authoritative)

PEP 257 — "Docstring Conventions" (Python Enhancement Proposal 257). The official Python convention for docstrings: where they go, the triple-quote rule, one-line vs. multi-line form, and what a good docstring should say. Short and foundational — read it once and you'll write docstrings correctly for the rest of your Python career. (Pair with PEP 8, Python's style guide, for naming and formatting, and PEP 484, which introduced type hints — the §24.4 material.)

JSDoc (jsdoc.app) — the JavaScript documentation convention. The reference for the @param / @returns / @throws block-comment format shown in §24.3, including how types in {braces} and optional [params] work. The "Getting Started" and "Block Tags" pages cover everything in this chapter and more; modern editors and TypeScript read JSDoc directly, so it pays double as docs and type information.

The Diátaxis framework (diataxis.fr), by Daniele Procida. A systematic map of documentation into four kinds — tutorials, how-to guides, reference, and explanation — and why mixing them fails. Code comments and docstrings are the reference corner brought down to the function level; this framework is the bridge to Chapter 25 (API docs) and the explicit subject of Chapter 26. Read it now to see where today's chapter sits in the larger documentation landscape.

Tier 1 — Books on writing code that explains itself

Robert C. Martin, Clean Code: A Handbook of Agile Software Craftsmanship (2008). Its chapters on Meaningful Names and Comments are the canonical long-form treatment of this chapter's two halves. Martin's stance is deliberately strong — "a comment is a failure to express yourself in code" — and worth reading precisely because it's stronger than this book's position: it sharpens the §24.5 idea that many comments should be designed out via better names, while §24.2 holds the line that the why still belongs in a comment. Read it as a bracing argument to wrestle with, not a rulebook to obey.

Steve McConnell, Code Complete (2nd ed., 2004), Chapter 32, "Self-Documenting Code." A thorough, balanced, evidence-minded treatment of comments and naming — more measured than Clean Code and closer to this chapter's "calibrated center." McConnell's distinction between comments that repeat the code (bad) and comments that explain intent (good) is precisely §24.2, argued at length and with care.

Andrew Hunt & David Thomas, The Pragmatic Programmer (1999; 20th-anniversary ed., 2019). The source of the widely repeated "DRY" principle (Don't Repeat Yourself), which applies to documentation too: a fact stated in both code and a comment is a duplication that will drift (§24.6). Its sections on comments and on documentation reinforce the chapter's preference for documentation that can't fall out of sync.

Tier 1 — The writing-craft roots (the why beneath the why)

William Strunk Jr. & E. B. White, The Elements of Style. "Omit needless words" is "comment the why, not the what," one domain over. The what-comment is the needless word of code documentation. Re-read the conciseness sections with code in mind and the connection is immediate.

William Zinsser, On Writing Well. Zinsser's "clutter is the disease of American writing" describes the over-documented file of Case Study 2 exactly: the narration that buries the signal. His chapter on simplicity is the prose ancestor of the documentation spectrum's too-much end.

Tier 2 — Attributed ideas and communities (real, widely held; cited honestly)

"Code is read far more often than it is written." A maxim long current in software engineering and frequently associated with guidance around Python's design (and echoed by many practitioners). The exact origin is diffuse, so treat it as a widely-attributed principle rather than a single sourced quotation — but the underlying claim (optimize code, and its documentation, for readers) is the empirical foundation of the whole chapter.

"Documentation is a love letter you write to your future self." A line widely circulated in programming communities (often attributed to Damian Conway) capturing the §24.1 audience point. Attributed, not precisely sourced; the sentiment is the reusable part.

Write the Docs (writethedocs.org). A global community of documentation practitioners — engineers and technical writers — whose talks, guides, and conference archives are an excellent, free, continuously-updated resource on every topic in Part V, including code-level docs. A good place to keep learning after the chapter ends.

A note on the citation tiers (this book's own §8 practice): the conventions above (PEP 257, JSDoc, Diátaxis) and the books are Tier 1 — real, verifiable, and named precisely. The two quotations are Tier 2 — genuine, widely-attributed ideas whose exact provenance is diffuse, so they're flagged as attributed rather than given invented sources. No DOIs, years, or editions have been fabricated; where an edition is given it's the standard one.

Back to: Chapter 24 · Key Takeaways · Exercises