Prefer deep modules — small interface, powerful implementation
Deep modules over shallow
Ousterhout, A Philosophy of Software Design Ch. 4.
Definition
| Shape | Interface | Implementation | Hides |
|---|---|---|---|
| Deep | Simple, narrow | Complex, powerful | Lots |
| Shallow | Nearly as complex as impl | Thin | Nothing |
Visual: deep = tall thin rectangle. Shallow = short wide rectangle. Interface = top edge. Implementation = area.
Goal: maximize hidden complexity per unit of exposed surface.
Why agents thrive on deep modules
| Benefit | Mechanism |
|---|---|
| Obvious test boundary | Draw ring around module → meaningful test. Shallow module = ring around nothing. |
| Gray-box delegation | Human pins interface. Agent free-fires on impl. |
| Fewer cross-module deps | Narrow interfaces = fewer callers reasoning about internals. |
| Cache-friendly context | Load one deep module + interface = enough. Load 20 shallow ones = context bloat. |
Anti-patterns — shallow modules
- Wrapper class delegating each call 1:1 to inner object
- Class with 20 tiny public methods, each calling one other method
- "Manager" / "Helper" / "Utils" classes with no encapsulated logic
- Getters/setters exposing every field (interface = impl)
- Pass-through layers ("service" calling "repository" calling "dao")
Refactor question
Before splitting a module: can interface get simpler at cost of richer implementation?
If yes → merge, not split. Push complexity down, not sideways.
If no → split justified.
When shallow is OK
- Truly minimal wrapper for FFI / external SDK boundary
- Adapter pattern where the shim IS the value
- Test doubles
Everywhere else: deepen.
Source
- John Ousterhout, A Philosophy of Software Design Ch. 4 — https://web.stanford.edu/~ouster/cgi-bin/aposd.php
- Reinforced by Matt Pocock workshop 2026-07-03
Cross-refs
- [[feedback-loops-are-the-ceiling]] — deep modules → obvious test boundaries → better loops
ponytail§Reuse existing patterns — same taste, different frame- [[match-surrounding-style]] — deep-module principle applies at file-org level too