codebase-design — deep modules, small interfaces

Leverage for callers, locality for maintainers, testability for everyone. (Distilled in our own way from Matt Pocock's codebase-design, MIT — Ousterhout's A Philosophy of Software Design crossed with Feathers' "seam".)

Vocabulary (use these words exactly — consistent language is the whole point)

• Module — anything with an interface + implementation (function, class, package, a tier-spanning slice). Not "component / service / unit".
• Interface — everything a caller must know to use it correctly: the type signature plus invariants, ordering, error modes, required config, performance. Not just the "API / signature".
• Implementation — the code inside.
• Seam (Feathers) — a place you can change behaviour without editing there; where a module's interface lives. Not "boundary" (overloaded with DDD).
• Adapter — a concrete thing that satisfies an interface at a seam.
• Depth — leverage at the interface: how much behaviour a caller/test can exercise per unit of interface they must learn.
• Leverage — one implementation pays back across N call sites and M tests. Locality — change/bugs/knowledge concentrate in one place; fix once, fixed everywhere.

Deep vs shallow

Deep = small interface, lots of behaviour. Shallow = interface nearly as complex as the implementation (a pass-through) — avoid. When shaping an interface, ask: (1) fewer methods? (2) simpler parameters? (3) hide more complexity inside?