codebase-design

Topics in the source

• Codebase Design
• Glossary
• Deep vs shallow
• Principles
• Designing for testability
• Relationships
• Rejected framings
• Going deeper

Design deep modules: a lot of behaviour behind a small interface, placed at a clean seam, testable through that interface. Use this language and these principles wherever code is being designed or restructured. The aim is leverage for callers, locality for maintainers, and testability for everyone. Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point. Module: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. Avoid: unit, component, service. 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. Avoid: API, signature (too narrow, they refer only to the type-level surface). Implementation: what's inside a module, its body of code. Distinct from Adapter: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise. Depth: leverage

This is an excerpt. Refer to the complete source and its current requirements.