Pull Complexity Downward

When complexity is unavoidable, it is better to absorb it inside a module's implementation than to expose it through the interface. The module developer suffers so that every user does not.

Why it Matters

An interface's complexity is paid by everyone who uses the module, repeatedly, forever; an implementation's complexity is paid once, by one person. Pulling complexity down trades a one-time cost for the removal of a recurring, multiplied one.

Signals

• A configuration option exists only because the implementer did not want to decide; the decision is pushed onto every caller.
• Callers routinely write the same boilerplate to use a module correctly.

Benefits

Simpler, smaller interfaces; fewer ways for callers to use the module wrong; complexity concentrated where it can be understood as a whole.

Risks

Taken to an extreme, an implementation can absorb so much that it becomes unmaintainable, or it can guess wrong on behalf of callers who genuinely needed control. Pull down what is truly general; do not bury decisions that callers must own.

Tensions

Directly opposes the instinct to "keep modules simple" by exposing knobs and shoving hard cases onto the caller. Simplicity for the implementer is not the goal; simplicity for the system is.

Examples

A text editor module that exposes a single insert operation and handles line-splitting internally pulls complexity down. One that makes every caller check and handle line boundaries has pushed it up.