Modules

Modules

• Depth is leverage at the interface. A module is deep when callers exercise a lot of behavior per fact they have to learn. It is shallow when the interface is nearly as complex as the body. Reduce methods, simplify parameters, hide more inside.
• Apply the deletion test. Imagine deleting the module. If complexity vanishes, it was a pass-through. If the same complexity reappears across N callers, it was earning its keep.
• The interface is the test surface. Callers and tests cross the same seam. Tests assert observable outcomes, not internal state. If a test has to change when the implementation changes, it is testing past the interface.
• One adapter is hypothetical. Two make a seam. Do not introduce a port unless at least two adapters are justified, typically production and a test stand-in. A single-adapter seam is just indirection.
• Keep internal seams internal. A deep module may be composed of small, swappable parts used by its own tests. Do not expose those parts through the external interface just because tests touch them.
• Accept dependencies. Don’t construct them. Inject the payment adapter, the SMS port, the clock. Construction belongs at the composition root. A module that news up Stripe inside submit cannot be tested through its interface.
• Replace tests. Don’t layer them. When shallow modules merge, delete the old unit tests. Write new ones at the deepened interface. Tests that survive only by knowing the old shape are waste.
• Use the vocabulary on purpose. Say module, interface, seam, adapter, depth, leverage, locality. Do not substitute component, service, API, or boundary, those words already mean other things here.