A Philosophy of Software Design Part 6 - Design Twice, Then
Leave the Reasons 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 11 Design it Twice and Chapter 12 Why
Write Comments?
The Four Excuses.
It uses only short key phrases from the source and turns the
reading into summary, interpretation, and application.
The guiding question is: What possibilities disappear when the
first design is never challenged?
How to use this note This is part 6 of a ten-part reading of A
Philosophy of Software Design.
The scope is Chapter 11 Design it Twice and Chapter 12 Why Write
Comments?
The Four Excuses.
The operating principle remains: book notes are storage; insight
cards are currency.
L0 · Entry Core sentence: Comparing design alternatives and
writing good comments are both ways to expose invisible reasons.
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: Comments are often treated as explanations
attached after code.
This range raises them into a tool for preserving design
rationale.
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 11 Design it Twice and Chapter 12 Why Write
Comments?
The Four Excuses L1 · Captures Short phrase · design "design it
twice" This treats the first design as a candidate, not a
standard.
Alternatives reveal hidden assumptions.
Short phrase · design "self-documenting" This is the common
claim that good code can explain everything.
Clear code matters, but it cannot always express intent and
context.
Short phrase · design "well-written comments" These comments
preserve information not visible in code.
A good comment preserves judgment instead of repeating
mechanics.
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 Design twice Compare at least two design
alternatives Only comparison makes tradeoffs visible 2 Risk of
the first idea The first structure may come from familiarity
Design improves through comparison more than generation 3
Comment excuses Time pressure, self-documenting code, stale
comments, and worthless comments are examined Bad comments are
not proof that comments are useless 4 Benefits of good comments
Comments store abstractions, intent, and constraints Future
readers often need reasons more than mechanics Argument in one
paragraph: Comparing design alternatives and writing good
comments are both ways to expose invisible reasons.
Comments are often treated as explanations attached after code.
This range raises them into a tool for preserving design
rationale.
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 - I6.1 The
first design is a sample that starts comparison, not an answer A
Philosophy of Software Design - I6.2 A comment should be
long-term memory for design judgment, not a repetition of code A
Philosophy of Software Design - I6.3 Good code and good comments
carry different kinds of information L4 · Production Board
Outputs Blog draft: Part 6 as "Design Twice, Then Leave the
Reasons" Code review question: What possibilities disappear when
the first design is never challenged?
Insight card: The first design is a sample that starts
comparison, not an answer L5 · Review Connections: This connects
to Architecture Decision Records: local comments and separate
decision records can complement each other.
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: Design quality comes less from the brilliance of
the first idea than from comparing alternatives and preserving
reasons.