designing-deep-moduleslisted

# Deep Module Design A **deep module** hides substantial complexity behind a small, simple interface. A **shallow module** exposes an interface nearly as complex as its implementation. "Module" means any abstraction boundary: function, class, package, service, or API. Every module has: - **Cost**: its interface — parameters, methods, exceptions, configuration, preconditions, side effects, imported types - **Benefit**: the functionality hidden behind that interface A module justifies its existence only when benefit substantially exceeds cost. ## Workflow: Designing a new module 1. Identify the design decision the module will hide (storage format, protocol, business rule, algorithm). 2. Design the interface for the 90% common case first — zero unnecessary parameters, zero ceremony. 3. Verify the interface is expressed in terms of what the module *does*, not how it does it. 4. Pull complexity downward: if a decision can be made internally with reasonable defaults, make it internally. 5. Define errors out of existence: if the module can satisfy the caller's intent without surfacing an error, do so. 6. Add escape hatches for the 10% case only where genuinely needed, without complicating the common path. 7. Verify: articulate what significant decision the module hides. If you cannot, it may be too shallow. ## Workflow: Reviewing existing code for depth 1. Identify module clusters with these shallow signals: - Long call chains (4+ layers before real work happens) - Mir