A Philosophy of Software Design Part 7 - Comments and Names
Should Carry Intent A Philosophy of Software Design treats
software design less as architectural theater and more as the
daily work of managing complexity.
This part covers Chapter 13 Comments Should Describe Things That
Aren't Obvious from the Code and Chapter 14 Choosing Names.
It uses only short key phrases from the source and turns the
reading into summary, interpretation, and application.
The guiding question is: What can the reader infer from the
code, and what must be taught separately?
How to use this note This is part 7 of a ten-part reading of A
Philosophy of Software Design.
The scope is Chapter 13 Comments Should Describe Things That
Aren't Obvious from the Code and Chapter 14 Choosing Names.
The operating principle remains: book notes are storage; insight
cards are currency.
L0 · Entry Core sentence: Good comments and good names build the
model a human needs, not the procedure a machine already
executes.
Why read this: As AI tools and automation make code faster to
produce, I want sharper standards for code that remains
understandable and changeable.
Initial hypothesis: If comments and names are treated as style
preferences, they cannot function as design tools.
This section treats expression as part of the interface.
Author context: John Ousterhout is a computer scientist known
for work in operating systems, distributed systems, Tcl/Tk, and
software design education at Stanford.
Scope: Chapter 13 Comments Should Describe Things That Aren't
Obvious from the Code and Chapter 14 Choosing Names L1 ·
Captures Short phrase · design "don't repeat the code" A comment
has low value when it repeats low-level behavior.
Repetition increases maintenance cost without adding insight.
Short phrase · design "interface documentation" This explains
the contract and expectations users need.
Interface comments build the user's mental model.
Short phrase · design "precise names" Precise names reduce the
need for separate explanation.
A name is a small document and a small abstraction.
Copyright boundary This public note does not reproduce long
source passages.
It uses chapter-level concepts and short phrases as anchors,
then provides transformative summary and commentary.
L2 · Map Range Summary Main claim --- ------ ---------
------------ 1 Comment conventions Agree on what to write and
where to write it Consistent comments are easier to find and
maintain 2 Do not repeat code Explain invisible reasons rather
than visible operations Comments should carry what code cannot
say 3 Lower-level comments Add precise meaning to details They
clarify complex expressions or conditions 4 Higher-level
comments Provide intuition for the whole flow They guide readers
at file and module level 5 Choosing names Choose words that
create an accurate image Ambiguous names become a source of bugs
Argument in one paragraph: Good comments and good names build
the model a human needs, not the procedure a machine already
executes.
If comments and names are treated as style preferences, they
cannot function as design tools.
This section treats expression as part of the interface.
In practice, this moves review questions from "does it work?"
toward "what must the next reader know in order to change it
safely?" Design is not a separate ceremony; it is embedded in
names, boundaries, exceptions, comments, layers, and performance
choices.
L3 · Insight Cards A Philosophy of Software Design - I7.1
Comments should carry the intent and constraints the code cannot
express A Philosophy of Software Design - I7.2 A name is a tiny
document and determines the precision of an abstraction A
Philosophy of Software Design - I7.3 Interface documentation
designs the user's model, not just the usage instructions L4 ·
Production Board Outputs Blog draft: Part 7 as "Comments and
Names Should Carry Intent" Code review question: What can the
reader infer from the code, and what must be taught separately?
Insight card: Comments should carry the intent and constraints
the code cannot express L5 · Review Connections: This connects
with Clean Code naming principles, but this book emphasizes that
names help define abstraction boundaries.
Open questions: Where does this part's red flag appear most
clearly in my current codebase?
What check would an AI coding agent need in order to apply this
principle reliably?
Final takeaway: Good names and comments are not decoration; they
are the design surface that gives readers the right model.