What you call vs how it works

Think of it when you decide what other code may see and rely on, or you notice code relying on how something works inside.

In everyday life

A restaurant menu is an interface: you order by name and price, and the kitchen may change how it cooks. A diner who expects dishes in menu order relies on something the menu never promised.

One case

A booking site’s room search returns rooms sorted by price. Nobody promised that order: it came from how the search worked inside. The phone app labels the first result “Cheapest room”. In March the search team makes the search faster, the order changes, and the app labels a $240 room as the cheapest while a $95 room sits third.

The app relied on an order nobody promised

The case, cell by cell1 cell = 1 search result, in the order shown

Is actually cheapest

nonoyesnono

App labels as cheapest

yesnononono

Price labeled "Cheapest"

$240

Lines the app team changed

The search team changed only the inside. The app broke because it relied on the inside.

Every case

Every callerCode that uses another piece of code by calling it by name. relies on what it can see, not only on what you promised. If a detail of the inside leaks out, such as an order, a field name or a timing, someone will build on it. Then a change to the inside breaks code you never touched. A clear interface states exactly what is promised and hides as much of the rest as it can, so the inside can change with less risk.

The word

Engineers call this

interface, implementationThe interface is what you must know to use a piece of code: its name, what you give it, what it gives back. The implementation is the work inside, which users of the code should not need to know.

Decide what callers may rely on, put that in the interface, and hide the rest. When a caller needs more, such as a sort order, add it to the interface on purpose.

Where this idea leads

is the outside of everyA named box of code
is best small over a lot of work, as in aSimple outside, deep insideHabits, Keep it contained
between two programs is called anThe menu of requestsFoundations, How systems talk
stays the same during aSame behavior, new shape

Skills that encode it

codebase-design Matt PocockDefines the interface as everything a caller must know, ordering constraints included, and keeps the rest in the implementation.
principle-test-behavior-not-implementation pstackTests assert only what users observe through the interface, so they keep passing when only the internals change.