4. Notes — Modules Should Be Deep

3 min readDec 10, 2019

The author Jhon Ousterhout’s experience has been very different from mine. It’s so great to learn the ideas from Jhon and I take the nodes that are pragmatically introduced in this chapter exposing a very great way to look at modules, interface, and functionality.

Modular design

In modular design, a software system is decomposed into a collection of modules that are relatively independent. From the system’s vision, these modules work together by calling each other’s functions or methods. That will be the dependencies between the modules which cause the modules need to change to match the change of the modified modules.For example, the arguments for a method crate a dependency between the method and any code that invokes the method.If the required arguments change, all invocations of the method must be modified to conform to the new signature.

The goal of modular design is to minimize the dependencies between modules.

Each modules contain two parts: Interface and implementation.

  • Interface: Consists of everything that a developer working in a different module must know in order to use the given module.
  • Implementation:Consists of code that carries out the promises make by the interface.

A Developer working in a particular module must understand the interface and the implementation of that module, plus the interfaces of any other modules invoked by the given module.

Best module define:

  • Module’s interface is much simpler than its implementation
  • Modify the module without changing the interface

What’s in an interface?

The module’s interface contains two kinds of information: formal and informal. Anything developer needs to know to use it.

  • Formal

Formal interface for a class consists of the signatures of all of its public method, plus the names and types of any public variable.

  • Informal

The informal interface is kind of interface, which describes constraints on the usage of a class(perhaps one method must be called before another) or anything else a developer needs to know a particular piece of information in order to use that module.

Informal interface can only be described using comments, and the programming language can not ensure that the description is complete or accurate.


An abstraction is a simplified view of an entity, which omits unimportant details. Each module provides an abstraction in form of its interface.

The interface presents a simplified view of module’s functionality, the details of the implementation are unimportant from the standpoint of the module’s abstraction.

An abstraction can go wrong in two ways

  • Increate the cognitive load when exposing too much details that are not really important.
  • Result in obscurity when hiding the important details

Deep modules

The best modules are those that provide powerful functionality yet have simple interfaces because only a small fraction of its internal complexity is visible to its users.

The area of each rectangle is proportional to the functionality implemented by the module. Tho top edge of a rectangle represents the module’s interface; the length of that edge indicates the complexity of the interface.

The best modules are those with greatest benefit and the least cost. The benefit provided by a module is its functionality and the cost of a module is its interface.

The system’s complexity consists of module’s interface which should be designed to make the common case as simple as possible

Shallow modules

A shallow module is one whose interface is relatively complex in comparison to the functionality that it provides. The extreme example showing the interface of the module is nearly as great as the complexity of its implementation. It provides no abstraction since all functionality is visible through its interface. It is no simpler to think about the interface than to think about the full implementation. At this point, the benefit less than or equal to the cost of a module

Red Flag:

A shallow module is one whose interface is complicated relative to the functionality it provides.Shallow modules don’t help much in the battle against complexity, because the benefit they provide is negated by the cost of learning and using their interfaces.Small modules tend to be shallow.