When to Use Deep Modules

Lesson 2 of the deep-module course · Advantages, disadvantages, and a decision framework · ~18 minutes

1 · What are deep modules? 2 · When to use them 3 · TypeScript module design
Why this matters for your mission Deep modules are not a golden hammer. Used wisely, they make code simpler. Used badly, they create black boxes that are impossible to debug. Today you learn the decision framework — when the benefits outweigh the cost, and when a simple function is better than a smart module.

Last lesson, we met the deep module: heavy inside, light outside. Now the hard part: knowing when to build one. We use the same logging module throughout, because real decisions only make sense with a real example.

1 · The three big advantages

1a. Change stays inside the module

Remember the logging module: callers write logger.info("Order placed"). If you want to change the log format from [INFO] date message to {"level":"INFO","time":"..."} (JSON), you edit one file — the barrel — and no caller changes a single line. Compare that to the shallow version where every logger.log(...) call hard-codes the format.

This is the #1 reason deep modules pay off: the system evolves by changing the module, not the world around it.

1b. The module can grow without growing its interface

A deep module can add secret features — features the caller never sees — because the interface stays the same. The logging module can start writing to disk in batches behind the scenes. It can start dropping messages under high load to protect memory. The callers do not need to know. The interface — logger.info(msg) — never changes.

The principle Extensibility without interface growth — a deep module can get smarter over time while the caller's code stays exactly the same. That is the compounding value of depth.

1c. Bugs get contained, not contagious

In a shallow module, the caller handles level validation, timestamp parsing, format selection, and destination routing. If the caller makes a mistake — passes "infp" instead of "info" — the bug spreads. In a deep module, those details are impossible to get wrong — the caller never touches them. The module owns the invariants.

2 · The two big disadvantages

The black-box problem
// Something is wrong — no logs appear. But the
// logger silently swallowed them. Where?
// Inside the module. Good luck finding it.

logger.info("Order placed");
// …nothing. Was it the level? The destination?
// The error handling? All hidden.
The over-abstraction trap
// You need one call to log to a file,
// another to a network stream.
// The deep module assumed one destination.
// Now you fight the abstraction.

logger.info("Order placed", { destination: "file" });
// ^ the clean interface just got messy

2a. Debugging is harder

When a deep module misbehaves, the problem is inside the "black box". You cannot see the level filtering, the format selection, the error handling — all hidden by design. Ousterhout calls this the abstraction penalty: the very thing that makes the module easy to use also makes it hard to debug.

2b. Over-abstraction bites back

A deep module that guesses what callers need will eventually guess wrong. You need a slightly different format for one call, or a second destination, and the clean interface now has a new parameter — which erodes the depth. The cleanest interface is the one that matches all real use cases. If it doesn't, the module was over-designed.

Gotchas (1) Deep modules are not always better — a module that does little useful work should stay shallow (a one-line function is better than a wrapper class). (2) "Deep" is not a synonym for "complicated" — a deep module has a simple interface. (3) The best deep modules are honest — what they promise is what they deliver, no hidden surprises.

3 · A decision framework

Use this checklist before building a deep module:

Signal to build a deep moduleSignal to stay shallow
3+ callers need the same logicOnly one caller exists
The logic has real edge casesThe logic is a single line
You can name a stable interfaceYou are still guessing at the shape
The concept maps to a real thingIt is just a utility, not a concept
Rule of thumb Build deep when the problem is genuinely complex and used in multiple places. Keep shallow when it is trivial or unique. Premature abstraction is the cost of building a deep module too early — you guessed the interface before you understood the problem.

4 · Practice: filter inside, not outside

The logging module's callers never decide whether a message passes the level filter — the module handles that. Write levelOrder: a function that, given a severity name, returns a number so that "error" > "warn" > "info" > "debug". Then write shouldLog(messageLevel, minLevel) that uses it. This is the kind of logic a deep module keeps inside.

5 · Retrieval check

Answer from memory — that effort is the point. Do not scroll back up first.

6 · Where this goes next

You can now decide when a deep module is worth building, and you know the tradeoffs. Next lesson: building deep modules in TypeScript — using export, barrel files (index.ts), and types to make your module's interface tight and clean.

Your teacher is the agent Questions about the trade-offs — "what if everyone needs a different destination?" or "is the abstraction penalty real?" or "should I add logging levels now or later?" — ask in chat.
Primary source for this lesson Chapter 17 of A Philosophy of Software Design — John Ousterhout (2019). The chapter on "design comes first" covers the abstraction penalty and why you should avoid premature design.