deep-modules

Deep Modules Review Lens

When invoked with $ARGUMENTS, focus the analysis on the specified file or module. Read the target code first, then apply the checks below.

Evaluate whether modules provide powerful functionality through simple interfaces.

When to Apply

• Reviewing a new class, module, or API design
• When a module feels like it "doesn't do enough" or has too many parameters
• When you see many small classes collaborating to do one thing
• When a method signature closely mirrors what it calls
• During refactoring to decide what to merge or deepen

Core Principles

The Depth Principle

Every module gives functionality and costs knowledge (in the form of an interface). Deep modules give a lot and ask for very little, delivering the highest return on interface cost. This is the same interface-vs-implementation-cost asymmetry pull-complexity-down's "Core Asymmetry" applies to caller burden — here it's applied to depth.

The deepest possible module can even have no interface at all. Garbage collection is the classic example: it does enormously complex work that callers never think about.

Importantly, interfaces are also bigger than they look. The visible part is the formal interface: signatures, types, and exceptions. The invisible part is the informal interface: ordering rules, side effects, performance characteristics, and thread safety assumptions. The informal interface is usually larger and more dangerous. When the invisible part goes undocumented, callers end up with dependencies they don't know exist, creating new unknown unknowns.

The Depth Test

For each module under review:

1. How many things must a caller know to use this correctly?
2. How much work does the module do behind that interface?
3. Could a caller skip this module and do the work directly with similar effort?

If #3 is "yes," the module is shallow.

A concrete signal: if the documentation for a method would be longer than its implementation, it is shallow.