Lesson 2 of the deep-module course · Advantages, disadvantages, and a decision framework · ~18 minutes
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.
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.
A deep module can add secretem> 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.
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.
// 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.
// 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
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.
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.
Use this checklist before building a deep module:
| Signal to build a deep module | Signal to stay shallow |
|---|---|
| 3+ callers need the same logic | Only one caller exists |
| The logic has real edge cases | The logic is a single line |
| You can name a stable interface | You are still guessing at the shape |
| The concept maps to a real thing | It is just a utility, not a concept |
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.
Answer from memory — that effort is the point. Do not scroll back up first.
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.