Software Design

Apply John Ousterhout's "A Philosophy of Software Design" principles pragmatically — focus on the highest-impact issues, not dogmatic compliance.

Mode Selection

Determine mode from context:

• Review mode: User asks to review, audit, or refactor existing code
• Design mode: User is designing new modules, APIs, abstractions, or architecture
• Both: Large tasks involving redesign of existing code

Review Mode

1. Read the code under review

Read all relevant files. Build a mental model of module boundaries, interfaces, and information flow.

2. Evaluate against core principles

For each module/class/function, assess (see references/principles.md for details):

Principle	Key question
Depth	Does this module hide significant complexity behind a simple interface?
Information hiding	Are implementation details leaking across module boundaries?
Cognitive load	How much must a developer know to use or modify this code?
Change amplification	Would a simple change require edits in many places?
Obviousness	Can a reader understand behavior quickly without deep investigation?
Interface comments	Do comments describe the abstraction, not repeat the code?
Design in reviews	Are code reviews evaluating design quality, not just correctness?
Strategic investment	Is ~10-20% of dev time going toward design improvements?

3. Scan for red flags

Check for red flags from the book (see references/red-flags.md for complete list):

• Shallow modules (complex interface, little functionality)
• Pass-through methods/variables
• Information leakage between modules
• Temporal decomposition (split by when, not by what)
• Conjoined methods (can't understand one without reading another)
• Overexposed configuration parameters

4. Report findings

For each issue found:

**[Principle violated]** — severity: high|medium|low
Location: file:line
Problem: What's wrong and why it matters
Suggestion: Concrete improvement with brief rationale

Prioritize by impact. Skip low-severity issues unless explicitly asked for exhaustive review. Always explain WHY something is a problem in terms of complexity consequences (cognitive load, change amplification, unknown unknowns).

5. Score the design (0-10)

End every review with an overall score:

• 9-10: Deep modules, clean abstractions, excellent information hiding, comments capture design intent
• 7-8: Solid design with minor issues — a few shallow modules or small leakage
• 5-6: Mixed — some good abstractions but notable complexity problems
• 3-4: Significant issues — shallow modules, widespread leakage, tactical shortcuts
• 0-2: Pervasive complexity — unknown unknowns everywhere, no clear abstractions

Always state the current score and the specific changes needed to reach the next level. Example: "Current: 6/10. To reach 8: merge the 3 shallow service wrappers into a single deep module, and encapsulate the JSON format knowledge that leaks between Parser and Writer."

Design Mode

1. Understand the requirement

Clarify what the module/API/system needs to do. Identify the key use cases.

2. Apply "Design it twice"

Propose at least two alternative designs. For each, evaluate:

• Interface simplicity: How many concepts must users understand?
• Depth: How much complexity does the interface hide?
• Information hiding: What decisions are encapsulated vs. exposed?
• Generality: Is it somewhat general-purpose without being over-engineered?

3. Guide toward deep modules

Steer designs toward:

• Simple interfaces with powerful implementations
• Fewer, more capable classes over many tiny ones
• Pulling complexity downward — make the module's life harder so callers' lives are easier
• Defining errors out of existence — choose semantics that eliminate error conditions
• General-purpose interfaces with specialized implementations when appropriate

4. Validate with red flags

Before finalizing, check the proposed design against references/red-flags.md. If any red flags appear, iterate.

Pragmatic Application

These are guidelines, not laws. When reviewing:

• A shallow method that improves readability at call sites is fine
• Comments explaining "why" are valuable; don't demand them for obvious code
• Small helper functions for repeated 3-line patterns are acceptable
• Perfect information hiding is not always worth the refactoring cost

Always weigh the cost of change against the complexity reduction. Recommend changes only when the net benefit is clear.