codebase-design

Codebase Design

DesignDeep Modules: Hide a large amount of behavior behind a small interface, place the interface at a clear seam, and test through that interface. Use these terms and principles when designing or refactoring code, with the goal of providing leverage for callers, locality for maintainers, and making tests happen naturally.

Use the loaded CONTEXT terms and RULE. If not yet loaded, follow the project knowledge protocol; if knowledge is unavailable, continue and state so truthfully.

Glossary

Use the following vocabulary consistently when discussing design. When referencing real code, preserve existing identifiers and project terminology; do not force renames for the sake of vocabulary consistency Service、API、Component or business boundaries.

Module: Any structure that has an interface and an implementation. It is independent of scale and can be a function, class, package, or cross-layer slice. When discussing design concepts, avoid substituting "unit," "component," or "service."

Interface: All the information a caller must know to use the module correctly. Not just type signatures, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. When discussing this complete surface, avoid the narrower "API" or "signature."

Implementation: The code inside a module. It is different fromadapter: an adapter describes the role at a seam, while an implementation describes its internal contents. Use "adapter" when discussing seams, and "implementation" otherwise.

Depth: The leverage an interface provides, that is, how much behavior a caller or test can invoke per unit of interface learned. A module is deep when a large amount of behavior is hidden behind a small interface; a module is shallow when the interface is almost as complex as the implementation.

Seam(Michael Feathers): A place where behavior can be changed without editing code at the call site, and also the place where a module interface resides. Where to place a seam and what the interface contains are two different design decisions. It is different from a business boundary in DDD.

Adapter: A concrete structure that satisfies an interface at a seam. It describes the role being filled, not the technology used internally.

Leverage: The benefit callers gain from depth. Each unit of interface learned yields more capability, and one implementation can serve multiple call sites and tests.

Locality: The benefit maintainers gain from depth. Changes, defects, knowledge, and verification are concentrated in one place rather than scattered among callers; fix once, effective everywhere.

Deep modules and shallow modules

Deep module = small interface + large implementation:

┌─────────────────────┐
│       小接口         │  ← 少量方法、简单参数
├─────────────────────┤
│                     │
│       深实现         │  ← 隐藏复杂逻辑
│                     │
└─────────────────────┘

Shallow module = large interface + small implementation (should be avoided):

┌─────────────────────────────────┐
│              大接口              │  ← 方法多、参数复杂
├─────────────────────────────────┤
│              薄实现              │  ← 只是转发
└─────────────────────────────────┘

When designing an interface, ask:

• Can the number of methods be reduced?
• Can the parameters be simplified?
• Can more complexity be hidden internally?

Principles

• Depth is a property of the interface, not of the implementation. A deep module can still be composed internally of small, mockable, replaceable parts, except that these parts are not part of the external interface. A module can simultaneously have implementation-private parts used by its own tests,internal seams, as well as theexternal seams。
• deletion test. Imagine deleting this module: if the complexity disappears with it, it was just a forwarding layer; if the complexity scatters back to multiple callers, it is providing value.
• The interface is the test surface. Callers and tests cross the same seam. If a test wants to cross the interface, the module shape is probably wrong.
• One adapter is a hypothetical seam; two adapters make a real seam. Introduce a seam only when change actually exists.

Design for Testability

A good interface makes testing happen naturally:

1. Accept dependencies; do not create dependencies internally.

   // 易于测试
   function processOrder(order, paymentGateway) {}
   
   // 难以测试
   function processOrder(order) {
     const gateway = new StripeGateway();
   }
   

2. Return results; do not only produce side effects.

   // 易于测试
   function calculateDiscount(cart): Discount {}
   
   // 难以测试
   function applyDiscount(cart): void {
     cart.total -= discount;
   }
   

3. Keep the surface area small. The fewer methods, the fewer tests needed; the fewer parameters, the simpler the test setup.

Relationships

• Amodulehas only oneinterface, used by callers and tests.
• Depthisa modulerelative to itsinterfaceproperty.
• A seamisthe module interfacethe location where it resides.
• Adaptersare located atseamsand satisfyinterfaces。
• Depthproduces for callersleverage, and for maintainerslocality。

Phrasings not adopted

• Measuring depth by the ratio of implementation lines to interface lines(Ousterhout): this rewards padding the implementation. Here, depth is measured by interface leverage.
• Understanding "interface" as the TypeScript interface keyword or a class's public methods: too narrow in scope; here, interface includes all facts the caller must know.
• Using "boundary" to mean seam: it is easily confused with DDD's bounded context; use "seam" or "interface" instead.

Go Deeper

• Deepen a group of modules together with dependencies: read DEEPENING.md, to learn dependency classification, seam discipline, and the "replace rather than stack" testing strategy.
• Explore different interface options: read DESIGN-IT-TWICE.md, have multiple parallel sub-agents design significantly different interfaces, then compare them by depth, locality, and seam location.