general-vs-special

Representation leakage in API design occurs when getters, setters, or defaults expose internal module details. You detect it by auditing interfaces for unnecessary parameters and policy decisions that should remain encapsulated inside the module rather than being passed through.

Caller-specific logic in a module appears as conditional branches, one-off parameters, or policy decisions embedded in lower-level code. Identify the general mechanism, separate the caller-specific branches, and simplify the interface to improve module reusability.

Assessing interface specialization involves evaluating whether the interface handles current requirements without unnecessary breadth. Look for unnecessary parameters and conditional branches that embed caller-specific policies, then separate that logic to make the interface more general.

Over-specialization makes modules harder to reuse because caller-specific branches and unnecessary parameters embed one-off policy decisions directly in lower-level logic. This prevents the interface from acting as a general mechanism, reducing its applicability across different contexts.

You should avoid a general interface when it becomes unnecessarily broad for current needs. If generalizing an API requires adding complex conditional branches or parameters to anticipate unknown future callers, it is better to keep the interface simple and specific.

Simplify an API interface with too many parameters by identifying the general mechanism and moving caller-specific decisions inside the module. Apply deeper encapsulation by replacing unnecessary parameters and exposed setters with sensible internal defaults.