Book Note: A Philosophy of Software Design Part 7 - Comments and Names Should Carry Intent

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. ^q01

“ Short phrase · #design

“interface documentation”

This explains the contract and expectations users need. Interface comments build the user’s mental model. ^q02

“ Short phrase · #design

“precise names”

Precise names reduce the need for separate explanation. A name is a small document and a small abstraction. ^q03

■ 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.