Part 3 · 1 chapters · ~10 min
A Philosophy of Software Design
Complexity as the enemy and its symptoms, deep modules with small interfaces, information hiding and leakage, defining errors out of existence, pulling complexity downwards, and strategic programming, with a deep ledger client and the red flags as they appear in frontend code.
5
A Philosophy of Software Design
A short book, and the most useful one in the course for code review. "Is this module deep?" and "where did this knowledge leak?" are two questions that improve almost any pull request.
code
// shallow: every caller handles idempotency, retries, units and error mapping
await http.post('/ledger/entries', { amount: naira * 100, key: uuid() }, { retries: 3 });
if (res.status === 409) { /* already posted? */ } else if (res.status >= 500) { /* retry? */ }
// deep: one call; the module owns kobo, keys, retries and the 409 meaning
const entry = await ledger.post({ account: 'acct_7', amount: Money.naira(1500) });
// inside: integer kobo, a deterministic idempotency key, retries with jitter on 5xx,
// 409 → fetch and return the existing entry (an error defined out of existence)| red flag (the book's list, paraphrased) | what it looks like in a frontend codebase |
|---|---|
| shallow module | a useFetchUser hook that is one line around useQuery |
| information leakage | "amount in kobo" handled in twelve components |
| temporal decomposition | parseForm, validateForm, submitForm each knowing the schema |
| pass-through method | props drilled through five components that never use them |
| conjoined methods | two functions that cannot be understood without each other |
| hard to name | a component called Helper or Manager |
where it has aged, or argues
Ousterhout argues against parts of the very-small-functions and test-first style. His written debate with Robert C. Martin is worth reading for exactly that reason. Hold both views, and pick deep modules where an interface has many callers.
A PHILOSOPHY OF SOFTWARE DESIGN
John Ousterhout, 2018 (2nd ed. 2021): complexity is the enemy
swipe the figure sideways, or tap expand for full screen
1/6
Complexity is the enemy
Complexity: Ousterhout defines it by its symptoms: change amplification (a simple change touches many places), cognitive load (how much you must know), and unknown unknowns (not knowing what you need to know). Its causes are dependencies and obscurity.