PresidenteOG Deep Modules
Adapted from https://github.com/mattpocock/skills (mattpocock/skills, MIT), which draws on John Ousterhout's A Philosophy of Software Design — rewritten, not copied.
The terms
| Term | Meaning |
|---|---|
| Module | Any unit with an inside and an outside: a function, a file, a class, a package |
| Interface | What a caller must know to use the module: signatures plus the informal contract |
| Depth | Ratio of behaviour to interface. Deep = much behaviour, small interface. Shallow = interface nearly as large as the implementation |
| Seam | The boundary where you observe behaviour without reaching inside; where tests attach |
| Adapter | A thin module translating one interface to another; pushes a mess into one place |
| Leverage | How much a change behind the interface buys you without callers noticing |
| Locality | Related things kept close; a change touches one place, not ten |
Using it
- Prefer deep. A module earns its interface by hiding more than it exposes. If the interface is nearly as complex as what it hides, inline it: the abstraction is a tax.
- Put the seam where behaviour is observable and stable, and test there. If the seam keeps moving, the module's responsibility is not decided yet.
- Information hiding is the point. Each design decision known to one module and not leaked through its interface is leverage banked.
- Pull complexity downward. Better for the module to be complicated than its interface.
Relation to other skills
Feeds test-seams (tests attach at seams) and context-glossary (module names come from the domain terms). Not a substitute for refactoring-ui (visual polish) or tech-debt-auditor (finds existing debt): this is the vocabulary for the design conversation itself.