Information hiding, abstraction and interfaces

The principle: hide what is likely to change

In Section 3.1 David Parnas's KWIC example showed that decomposing a program by processing steps spread each design decision across several modules. His alternative, information hiding, gives each module one decision to keep secret: how lines are stored, how shifts are computed, when sorting happens. The module's interface is chosen to reveal as little as possible about that decision. Everything else in the system depends only on the interface, so the decision can change without them noticing.

Parnas's list of things worth hiding is still a good checklist half a century later: data structures and how they are stored; the sequence in which operations are carried out; the details of hardware, devices and operating systems; formats of input and output; and algorithms that might be replaced by better ones. Modern additions follow the same logic: which third-party provider is used, which database, which message broker, which version of an external API, and which business rules are under review.

The principle applies identically at every scale. A class hides its fields; a package hides its internal modules; a service hides its database, its language and its deployment; an organisation's public API hides which services exist behind it. In each case, what is hidden can change cheaply, and what is exposed becomes expensive to change because others depend on it.

Encapsulation is not information hiding

The two terms are often used as synonyms, but they mean different things. Encapsulation is a mechanism: bundling data with the operations on it and restricting direct access, through private fields, module boundaries or access modifiers (Section 0.3). Information hiding is a design principle: deciding which decisions to keep secret, and designing the interface so that it does not reveal them. Encapsulation is one of the tools you use to hide information; it does not decide for you what to hide.

It is easy to encapsulate perfectly and still hide nothing. A class with private fields and a public getter and setter for each of them is fully encapsulated, yet every caller knows exactly which fields exist and what types they have. Change the internal representation and every caller breaks. The opposite also happens: Python offers no enforced privacy at all, yet a well-designed Python module can hide its decisions very effectively through a carefully chosen set of functions.

# Encapsulated, but the representation leaks through the interface
class Price:
    def __init__(self, pounds: float):
        self._pounds = pounds
    def get_pounds(self) -> float:          # callers now depend on 'float pounds'
        return self._pounds
    def set_pounds(self, value: float):
        self._pounds = value

# Information hiding: callers ask for what they need, not for the field
class Money:
    def __init__(self, minor_units: int, currency: str):
        self._minor, self._currency = minor_units, currency
    def add(self, other: "Money") -> "Money": ...
    def allocate(self, ratios: list[int]) -> list["Money"]: ...
    def format(self, locale: str) -> str: ...
# Switching from pence to a decimal type later changes only this class.

Abstraction and interfaces as contracts

An abstraction is a simplified view of something that keeps what matters for a purpose and leaves out the rest. A file is an abstraction over disk blocks, caches and drivers; a payment is an abstraction over a card network, a provider's API and a bank's settlement process. Abstraction and information hiding are two sides of the same act: choosing an abstraction decides what the interface shows; hiding the rest makes the abstraction safe to rely on.

An interface is therefore a contract between a module and its users. Its formal part is what a type checker or API schema can see: operation names, parameter and return types, error types, field names in a JSON body. Its informal part is just as binding: what the operation does, its side effects, whether it can be retried safely, how long it takes, which errors are possible and what they mean. John Ousterhout stresses that the informal part can only be captured in documentation, and that if users must read a module's code to learn how to use it, the module provides no real abstraction.

Design by contract

Design by contract, developed by Bertrand Meyer in the 1980s with the Eiffel language and described in his book Object-Oriented Software Construction and his 1992 article Applying 'Design by Contract', makes the contract precise. Each operation has a precondition, which the caller must make true before calling; a postcondition, which the operation guarantees on return if the precondition held; and each class or module has invariants, conditions that hold between every pair of operations. The contract assigns responsibility: if a precondition is broken the bug is in the caller; if a postcondition is broken it is in the supplier.

Meyer argued against the opposite habit, defensive programming, in which every routine checks everything in case someone calls it wrongly. Redundant checks add code, complexity and new failure paths. Instead, each condition should be the clear responsibility of one side. A routine with a demanding precondition is simpler; a routine with a tolerant one is easier to call; the choice is a design decision, made explicitly. At the boundaries of a system, where input comes from untrusted users or other organisations, validation is not optional: there the contract says that the boundary module itself checks everything (Chapter 8).

class Account:
    """Invariant: balance_pence >= -overdraft_limit_pence."""

    def withdraw(self, amount_pence: int) -> None:
        # Preconditions (the caller's obligations)
        if amount_pence <= 0:
            raise ValueError("amount must be positive")
        if self.balance_pence - amount_pence < -self.overdraft_limit_pence:
            raise InsufficientFunds(self.id)
        old = self.balance_pence
        self.balance_pence -= amount_pence
        # Postcondition (the supplier's guarantee)
        assert self.balance_pence == old - amount_pence
        assert self.balance_pence >= -self.overdraft_limit_pence  # invariant

The same three ideas scale up to services. An API specification, such as an OpenAPI document, states the preconditions (required fields, formats, authentication), the postconditions (the response and the state change, such as an order exists with status PLACED) and the invariants a client may rely on (an order's total never changes after payment). Consumer-driven contract tests, in which each client publishes the expectations it relies on and the provider runs them in its build, check those contracts automatically.

Leaky abstractions

In November 2002 Joel Spolsky published The Law of Leaky Abstractions, which states that All non-trivial abstractions, to some degree, are leaky. A leaky abstraction is one whose hidden details still affect its users. TCP presents a reliable stream over an unreliable network, until a cable is cut and it cannot. SQL lets you state what you want, not how to get it, until two logically equivalent queries differ in speed by a factor of a thousand and you have to read the query plan. An object-relational mapper hides SQL until a loop quietly issues one query per row.

The consequence for architects is not that abstractions are bad, but that an interface should be honest about the details that will leak. The classic example is the remote call that looks exactly like a local function call. Network calls are slower by orders of magnitude, can time out, can succeed on the server while the response is lost, and can fail independently of the caller; Section 6.1 lists these as the fallacies of distributed computing. A good remote interface exposes this: it takes a timeout, returns errors that distinguish rejected from unknown outcome, and accepts an idempotency key so that retries are safe. Hiding the network completely is the leak waiting to happen.

Deep and shallow modules

John Ousterhout's A Philosophy of Software Design (first published in 2018; second edition 2021) offers a useful way to judge an interface. Think of every module as a rectangle: the top edge is its interface, which every user has to learn, and the area is the functionality it provides. A deep module has a small interface over a lot of functionality, so it pays back the cost of learning it many times over. A shallow module has an interface nearly as complex as what it does, so it adds cost without hiding much.

His favourite example of depth is Unix file input and output: a handful of calls (open, read, write, seek, close) hide file systems, disk layout, caching, permissions, devices and concurrent access. His example of shallowness is a class whose methods each forward one call to another class, or a linked-list class whose interface exposes almost everything it does. Ousterhout argues that the common advice to keep classes and methods very small can produce what he calls classitis: many shallow classes whose interfaces together add up to more complexity than one deeper module would.

Not everyone agrees with how far Ousterhout takes this. Advocates of small classes and functions, such as Robert C. Martin in Clean Code, argue that tiny units are easier to name, test and reuse; Ousterhout and Martin debated the point in a written exchange published in 2025. Both sides agree on the underlying goal, which is to reduce the complexity a reader has to hold in mind. At architecture scale the depth test is particularly valuable: a service whose API mirrors its database tables one to one, with create, read, update and delete for each, is shallow, and pushes all the real logic onto its clients.

Hyrum's law: everything observable becomes the contract

Hyrum's law, named after Hyrum Wright, then a software engineer at Google, by his colleague Titus Winters and popularised in Software Engineering at Google (2020), observes that with a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody. The order in which a function returns items from an unordered set, the exact wording of an error message, a field that is always present though documented as optional, the fact that a call takes 50 milliseconds: if users can see it, some of them will rely on it.

The law explains why information hiding has to be designed in, not hoped for. Every behaviour you expose by accident becomes part of the de facto contract, and changing it will break someone, however clearly the documentation said it was unspecified. Some teams deliberately randomise unspecified behaviour, such as iteration order, so that no one can come to depend on it; Go randomises map iteration order for this reason. Others keep response payloads lean, so there is less to depend on.

Designing stable APIs between components

Between components and services, interfaces are the most expensive things to change, because changing them requires coordinating with every consumer. The practices below follow from everything above; Section 0.6 introduced APIs and Section 7.7 covers schema compatibility in depth.

Worked example: a payment interface that hides the provider

A food-delivery company takes payments through Provider A. Finance wants to add Provider B for lower fees in one country, and to be able to switch providers within a day if one has an outage. Today the checkout code calls Provider A's SDK directly in eleven places, uses its error codes to decide what to show the customer, and stores its transaction objects in the orders table. Every one of those is a decision that has leaked.

The design introduces a PaymentGateway interface owned by the shop, not by any provider. It is expressed in the shop's own terms: amounts as integers in minor units with a currency, the shop's order identifier, an idempotency key and three outcomes. Each provider gets an adapter that implements the interface and translates to and from that provider's API, error codes and quirks. Configuration chooses the adapter per country. This is the same move as the intermediary in Section 2.6, now seen as information hiding: the hidden decision is which provider, and how it is called.

from typing import Protocol, Literal
from dataclasses import dataclass

@dataclass(frozen=True)
class PaymentResult:
    outcome: Literal["approved", "declined", "unknown"]  # unknown: safe to retry
    reference: str | None        # our reference, not the provider's object

class PaymentGateway(Protocol):
    def authorise(self, order_id: str, amount_minor: int, currency: str,
                  idempotency_key: str) -> PaymentResult: ...
    def capture(self, reference: str) -> PaymentResult: ...
    def refund(self, reference: str, amount_minor: int) -> PaymentResult: ...

class ProviderBAdapter:            # implements PaymentGateway
    def authorise(self, order_id, amount_minor, currency, idempotency_key):
        resp = self._client.create_charge(value=amount_minor / 100,   # B wants decimals
                                          currency=currency, key=idempotency_key)
        return PaymentResult(_map_status(resp.code), _store_ref(resp.id))

How professionals apply it

Experienced designers start an interface from the needs of its callers, written in the caller's language, and only then design the implementation. They keep a list of the decisions each important module hides and review new interfaces against it. They treat every public API as a product with a lifecycle (proposal, review, versioning, deprecation) because, by Hyrum's law, anything published will be used. And they accept that abstractions leak, so they make the leaks explicit: latency budgets, error semantics and retry rules appear in the contract.

Information hiding tells you what each module should keep to itself. It does not tell you which way the dependencies between modules should point, or what happens when they form loops. That is the subject of Section 3.4.