Skip to content

Deep vs. Shallow Modules

The best modules provide powerful functionality behind simple interfaces, because interface complexity is the cost paid by all users while implementation complexity is paid once.

Tension Addressed

Abstraction vs. Indirection

Recognizable As

Unix file descriptors (simple interface, complex implementation); classes where the public interface is much smaller than the private implementation; functions that do significant work behind simple signatures

Canonical Sources

Ousterhout, "A Philosophy of Software Design" (2018)

Transfers To

API Design (interface simplicity), Library API Designwer-to-surface ratio), Abstraction Layer Design

Shallow modules (where interface complexity approaches implementation complexity) provide little value and may indicate over-decomposition. The ideal is maximum functionality hidden behind minimal interface surface.