general-vs-special

General vs. Special-Purpose 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.

General-purpose modules are surprisingly simpler, deeper and less effort to build. They produce better information hiding and can even provide these benefits when used in a single context. Because a general-purpose interface doesn't need to know about specific callers, the knowledge always stays where it belongs.

When to Apply

• Designing a new module, API, or utility
• When a module has use-case-specific logic embedded in it
• When a module's interface is cluttered with rarely-used parameters
• When deciding between a flexible API and a specific one

Core Principles

The Generality Test

"What is the simplest interface that will cover all my current needs?" — John Ousterhout, A Philosophy of Software Design

Not "the most general interface possible." The target is somewhat general-purpose.

• Functionality: Scoped to current needs. Doesn't build features you don't need.
• Interface: General enough to support multiple uses. Doesn't tie it only to today's caller.

A general-purpose interface is usually simpler than a special-purpose one. Fewer methods means lower cognitive load. Fewer methods per capability is the signal of increasing generality.

Two companion questions:

• In how many situations will this method be used? If exactly one, it's over-specialized.
• Is this API easy to use for my current needs? If callers must write loops or compose many calls for basic tasks, the abstraction level is wrong.

Special-General Mixture

Special-purpose code mixed into a general-purpose module makes it shallower. Two forms:

At the Interface

Methods or parameters that only serve specific callers. The interface widens, and policy decisions from a higher layer get encoded in a lower one.

Inside Method Bodies

Special cases tend to show up as extra if statements. Instead of adding more of them, try to create a design where they disappear. A search function that returns null when nothing is found forces every caller to check for null before using the result. If you return an empty list instead, the check loop runs zero times on its own with no extra check required.