designing-deep-moduleslisted

# Designing Deep Modules ## Overview A module is two things: an interface, which is everything a caller must know to use it, and an implementation, which is everything else. A module's value is the ratio between them. Deep modules present a small interface over a lot of functionality; shallow modules present an interface almost as complicated as the code behind it, and so pay their own cost back in complexity. The best modules are deep. Getting depth wrong is the most common structural mistake in otherwise clean functional code, because splitting feels virtuous and each split adds an interface. ## When to use - Deciding what a new module or file exports - Reviewing an interface before other code depends on it - A codebase has many small files that each do almost nothing - A wrapper exists that only forwards to something else - Deciding whether a helper deserves its own module Not for: deciding whether two existing pieces of code belong together, which is [splitting-and-joining-code](../splitting-and-joining-code/SKILL.md). ## What counts as the interface In functional code the interface is larger than the export list. It is everything a caller must know, formal and informal: | Part of the interface | Formal? | Example | | --------------------- | ------- | ----------------------------- | | Exported signatures | Yes | `price : Booking -> Priced` | | Types in signatures | Yes | the fields of `Booking` | | Failure cases |