software-design-philosophy

A Philosophy of Software Design

Use Ousterhout's A Philosophy of Software Design, 2nd edition, to reduce the cost of understanding and changing software. Brooks' conceptual integrity is the second anchor. Return a named design or fix, its reason, and the next move.

Select the route

Use clean-code for a local naming or structure cleanup with no boundary decision, and tdd for test-first execution. Continue the requested work through that skill; selecting the proper method is not a new approval gate.

Shared design rules

Use these leitwörter to explain an actual design decision:

• strategic — invest a little design now so the next change is cheaper. The opposite is tactical ("just make it work") and the tactical tornado (the person who ships fastest by leaving a mess).
• deep module — a simple interface hiding a lot of functionality. Cost is the interface; benefit is what it hides. A shallow module costs about as much to learn as to inline.
• information leakage — one design decision reflected in two or more modules. That is a change ownership failure; give the decision one owner.
• design it twice — for any consequential interface, sketch two or three meaningfully different shapes before coding.
• stay strategic — when modifying existing code, do not tack on a special case that makes the design worse. Fit the change, or improve the design.
• decide what matters — name the few things this situation depends on, minimize that set, and emphasize only those.
• reader, not writer — complexity is judged by the next person to change the code. If it is simple only to you, it is complex.
• conceptual integrity / smallest coherent shape — one model, no larger than the problem.

Modelled sentence: "This is **tactical** — a special case on a **shallow module**. **Design it twice** keeps **conceptual integrity**; the cost is one extra hour now vs **information leakage** later."

A second modelled sentence, from the official extract: "`backspace(cursor)` is a **false abstraction** — the UI still has to know which characters vanish. One `delete(start, end)` has **leverage**; the special methods do not."

Evidence and authority

Inspect enough of the live code or stated design to identify the abstraction, the informal interface (everything a caller must know), and a relevant red flag or principle. Read further only when it could change the decision. With no repository, use the supplied constraints and mark assumptions.

Ask reader, not writer: would the next developer need a fact absent from the interface? That is evidence of leakage or obscurity. Reuse settled choices; alternatives belong to a consequential unresolved design decision, not every local edit.

review and all design-gate invocations are read-only: findings only, no edits or test runs. design and improve may edit within the user's request. They do not authorize unrelated refactors.

Acceptance contract

Use the selected mode's output fields. Name the official red flag or principle behind each finding. Report real rejected alternatives, or state that no new design choice was required. For edits, identify changed files, behavior-preserving work or exact behavior changes, and checks run or unavailable.

Under design-gate, return verdict (proceed | revise), conceptual_integrity_check, blocking_findings, advisory_findings, and required_changes. A leaked decision, shallow new public interface, or tactical special case can block when it is load-bearing; cosmetic naming is advisory.

Gotchas

1. Do not turn a one-line bug fix into a design exercise. Match effort to stakes.
2. Do not preserve an existing pattern when the broken model is the request.
3. Do not confuse consistency with conceptual integrity — repeating a mistake consistently is still a defect.
4. Do not invent findings to fill a category. clean is valid.
5. Do not quote or reconstruct source text from the book this skill distills.
6. Depth before length (ch. 9.8). After a few dozen lines, shortening a function rarely helps the system. More tiny functions means more interfaces and conjoined methods. Do not replace an earned comment with a ten-word method name. Small classes that leak one format are usually too many classes — merge them.
7. Do not hide a design decision in a commit message. Comments belong in the code.
8. private plus a getter is not information hiding. If callers must know the field exists, it is in the interface.
9. Lots of documentation is often a hard to describe flag, not a virtue. Simplify the design.

Chapter lookup

The selected mode links to its needed principles, red flags, and methods. Load references/chapter-map.md only to locate a question that does not fit those routes.