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

Work	Method to load
New module or consequential API/interface shape	references/design-mode.md
Change existing code while reducing its complexity	references/improve-mode.md
Assess a diff, design, PR, or design-gate input	references/review-mode.md

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 a consequential unresolved interface, compare two or three meaningfully different shapes before coding. Reuse a settled interface unless new evidence challenges it.
• 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.

In an interview, record the boundary decision, rationale, constraints, and source references in the existing decision record. Code edits, interface comments, test mechanics, and standalone reports belong to their later authorized stage.

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, use the caller's canonical gate result and put the conceptual integrity conclusion in review_focus. 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.