information-hiding

Information Hiding 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 modules encapsulate design decisions effectively.

When to Apply

• Reviewing module boundaries or class decomposition decisions
• When multiple modules change together for single-decision changes
• When private fields have matching getters and setters
• When modules are organized around execution steps (read/process/write)
• When a format, protocol, or representation appears in multiple places

Core Principles

Knowledge Ownership Test

For every design decision in the code (data format, algorithm choice, protocol, storage representation):

1. Which module owns this decision?
2. Is that ownership exclusive, and no other module knows this?
3. If this decision changes, does only one module need editing?

If #3 is "no," there is information leakage.

Two Kinds of Leakage

Interface Leakage

The decision appears in parameters, return types, or exceptions. Bad, but at least visible and discoverable.

Back-Door Leakage

Two or more modules encode the decision in their implementations with nothing in the code surface making the dependency visible. This maps directly to unknown unknowns: a developer modifying one module has no signal the other must change. More pernicious than interface leakage for exactly this reason.

Signs of back-door leakage:

• Changing an internal data structure breaks a seemingly unrelated module
• Two modules must be updated in lockstep but have no direct API dependency
• Shared assumptions about file formats, message ordering, or naming conventions that exist nowhere in the code or docs an agent could load into context
• Tests that break in module B when module A's internals change

Not all dependencies are eliminable. Transforming a hidden dependency into an obvious one is often more valuable than trying to remove it. At least then the next developer knows to look.