codebase-design

Codebase design

Design deep modules: substantial behavior behind a small interface, placed at a real seam and tested through that interface. Optimize for caller leverage and maintainer locality.

Vocabulary

• Module: anything with one interface and an implementation, from a function to a package.
• Interface: everything a caller must know: types, invariants, ordering, errors, configuration, and relevant performance behavior.
• Implementation: the behavior hidden inside a module.
• Depth: useful behavior per unit of interface a caller must learn.
• Seam: a place where behavior can change without editing the caller at that place.
• Adapter: a concrete implementation that satisfies an interface at a seam.
• Leverage: capability callers gain from a small interface.
• Locality: change, knowledge, bugs, and verification concentrated in one place.

Use these terms consistently. Prefer seam over the overloaded word boundary when discussing replaceable behavior.

Design checks

• Reduce methods and parameters when callers do not need the exposed choice.
• Hide repeated orchestration, invariants, and error handling inside the module.
• Apply the deletion test: deleting a useful module should make its complexity reappear across its callers. A layer whose complexity simply vanishes was probably a pass-through.
• Treat the interface as the test surface. Tests should survive internal refactors.
• Accept dependencies at real seams instead of constructing hard-to-replace externals internally.
• Introduce a seam for demonstrated variation. Production plus a meaningful test adapter can make two real adapters; a single speculative adapter does not.
• Return observable results where practical instead of requiring tests to inspect internal state.

For dependency-specific deepening, read DEEPENING.md. For a consequential interface with several plausible shapes, read DESIGN-IT-TWICE.md.