pull-complexity-down

Pull Complexity Downwards 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 complexity is absorbed into implementations or pushed up to callers.

When to Apply

• Designing or reviewing a module's interface
• When callers must do significant setup or configuration
• When callers handle errors or edge cases the module could handle internally
• When configuration parameters are being added to an API
• When evaluating decorator or wrapper patterns

Core Principles

The Core Asymmetry

One implementer, many callers. Complexity in the implementation is paid once. Complexity in the interface is paid by every caller. (The same asymmetry underlies deep-modules' "Depth Principle" — applied there to overall interface depth, applied here to which side of the interface should absorb a given piece of complexity.)

When developers encounter a hard problem, the path of least resistance is to push it upward: throw an exception, add a configuration parameter, define an abstract policy. These moves feel like good engineering. But all you have done is distribute the decision to a larger number of people who typically have less context.

Configuration Parameter Test - The Three AND Conditions

Configuration parameters are not a feature. They are a symptom of an incomplete module. Every parameter exported is a decision the developer chose not to make.

1. Different callers genuinely need different values, AND
2. The correct value cannot be determined automatically, AND
3. The impact is significant enough to justify the interface cost

If any condition fails:

• All callers use the same value → make it a constant
• The module can compute a good value → compute it dynamically
• The impact is negligible → pick a sensible default

Even for legitimate parameters, provide reasonable defaults so users only need to provide values under exceptional conditions.