A module is anything with an interface and an implementation. The term is deliberately scale-agnostic. It covers a function, class, package, or tier-spanning slice. Do not call it a unit, component, or service.
The interface is everything a caller must know to use the module correctly. It includes the type signature and also invariants, ordering constraints, and error modes. Required configuration and performance characteristics belong to it too. Do not call it an API or a signature, because those words cover only the type-level surface.
The implementation is the body of code inside a module. It differs from an adapter. A Postgres repository is a small adapter with a large implementation, and an in-memory fake is the reverse. Say "adapter" when the seam is the topic, and "implementation" otherwise.
Depth is leverage at the interface. It is the amount of behavior a caller or test can exercise per unit of interface it must learn. A module is deep when a lot of behavior sits behind a small interface. It is shallow when the interface is nearly as complex as the implementation.
A seam is a place where you can alter behavior without editing in that place. The term comes from Michael Feathers. A seam is the location where a module's interface lives. Where the seam goes is its own design decision, separate from what goes behind it. Do not call it a boundary, because DDD uses that word for bounded contexts.
An adapter is a concrete thing that satisfies an interface at a seam. The term names the role it plays, the slot it fills, and not what is inside it.
Leverage is what callers get from depth. They get more capability per unit of interface they learn. One implementation pays back across many call sites and many tests.
Locality is what maintainers get from depth. Change, bugs, knowledge, and verification concentrate in one place instead of spreading across callers. A fix in that one place fixes every caller.
Three questions help when you design an interface.
- Can the number of methods shrink?
- Can the parameters get simpler?
- Can more complexity move inside?
The first rule is to accept dependencies instead of creating them. This version is testable.
function processOrder(order, paymentGateway) {}
This version is hard to test.
function processOrder(order) {
const gateway = new StripeGateway();
}
The second rule is to return results instead of producing side effects. This version is testable.
function calculateDiscount(cart): Discount {}
This version is hard to test.
function applyDiscount(cart): void {
cart.total -= discount;
}
The third rule is a small surface area. Fewer methods need fewer tests, and fewer parameters need simpler test setup.