abstraction-quality

To identify shallow abstractions during code review, compare adjacent layers to see if they provide meaningfully different mental models or merely add redundant pass-through methods. Evaluate whether callers can use the abstraction without understanding its underlying implementation.

A shallow abstraction in software architecture is a layer or wrapper that fails to hide complexity, instead adding redundant boilerplate. Genuine abstractions provide conceptual boundaries and distinct mental models, while shallow ones leak implementation details and duplicate responsibilities across modules.

You should refactor false abstractions in a layered design when decorators or wrappers exhibit structurally shallow pass-through behavior. Expose, redistribute, or merge these false abstractions to eliminate redundant architecture and ensure remaining layers genuinely reduce complexity.

The decorator pattern can create shallow wrappers if it adds pass-through methods without meaningful depth. During architecture review, audit decorator behavior to determine whether it genuinely hides implementation details or merely adds boilerplate layers duplicating responsibilities.

Test implementation independence by verifying callers can interact with the abstraction's interface without needing knowledge of its underlying mechanics. If callers must understand internal details to use the wrapper, the abstraction is leaky and structurally shallow.