Simple outside, deep inside

Think of it when every caller of some code has to know the same many details to use it.

In everyday life

Like a car’s start button: one press, and the starter, the fuel pump and the electronics all do their work out of sight. A shallow car would ask the driver to start each part.

One case

A shop’s payment function takes 7 settings: the payment company, the currency, the retry count and four more. 15 places in the checkout call it, and each one sets all 7. The payment company changes how retries work, so the team edits all 15 callers and misses two. Those two pages fail every card payment for a day.

Simple outside, deep inside
The ideaKeep it contained
Simple outside, deep inside

A piece of code with a small, simple interface that hides a lot of work behind it. Callers learn little and get a lot.

Keep it contained, Habits

Every case

When the interface is almost as complex as the work inside, the module saves nobody anything. Every callerCode that uses another piece of code by calling it by name. repeats the same knowledge, and every change inside spreads out to every caller. A deep module keeps that knowledge in one place: “charge(order)” can hide the payment company, the currency, the retries and the receipt. A change inside it is made once, for every caller. A useful test: imagine you delete the module. If the same complexity then appears in every caller, the module was earning its keep.

The word

Engineers call this

deep moduleA piece of code with a small, simple interface that hides a lot of work behind it. Callers learn little and get a lot.

Keep the interface small and the inside deep. Hide every detail a caller does not need to decide.

Where this idea leads

Skills that encode it

  • codebase-design Matt PocockA deep module puts a lot of behaviour behind a small interface. The deletion test shows whether it earns its keep.
  • principle-minimize-reader-load pstackDemand interface compression: a broad interface that hides little makes readers learn both the surface and the inside.