Engineering
Codebase Design
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable.
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable.
Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.
Module — anything with an interface and an implementation.
Interface — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics.
Implementation — what's inside a module, its body of code.
Depth — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn.
Seam — a place where you can alter behaviour without editing in that place; the location at which a module's interface lives.
Adapter — a concrete thing that satisfies an interface at a seam.
Leverage — what callers get from depth: more capability per unit of interface they learn.
Locality — what maintainers get from depth: change, bugs, knowledge, and verification concentrate in one place.
Deep module = small interface + lots of implementation.
Shallow module = large interface + little implementation (avoid).
When designing an interface, ask:
Good interfaces make testing natural: