Codebase Design

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface.

Glossary

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 vs shallow

Deep module = small interface + lots of implementation.

Shallow module = large interface + little implementation (avoid).

When designing an interface, ask:

• Can I reduce the number of methods?
• Can I simplify the parameters?
• Can I hide more complexity inside?

Principles

• Depth is a property of the interface, not the implementation.
• The deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
• The interface is the test surface. Callers and tests cross the same seam.
• One adapter means a hypothetical seam. Two adapters means a real one.

Designing for testability

Good interfaces make testing natural:

1. Accept dependencies, don't create them.
2. Return results, don't produce side effects.
3. Small surface area. Fewer methods = fewer tests needed.