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):

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.