Change one, break another

Think of it when a small change touches many files, or a change in one place breaks something far away.

In everyday life

Five stage crew each take a cue from one actor’s exact line. If the actor rewords it, the cues are missed. With one stage manager calling the cues, the actor can change the words and only the manager must know.

One case

A food delivery app marks an order with the text “out_for_delivery” in its status fieldOne named value inside a record, such as the total of an order.. Five parts of the system check for that exact text: the driver screen, the customer screen, the support dashboard, billing and the email sender. A developer renames it to “en_route” and updates the two screens. The other three still look for the old text, so they show every active order as status unknown.

Five parts read the status text; two were updated
The case, cell by cell1 cell = 1 part of the system
Status name it should look for
newnewnewnewnew
Status name it looks for
newnewoldoldold
Parts showing "unknown"
3
Parts that read the text
5
A one-word rename needed five edits, because five parts relied on the same detail.

Every case

Two parts are coupled when one relies on the details of the other: its field names, its order of steps, its timing. Each such tie is a place where a change can break something far away. Many ties make every change slow and risky, because you must find every place that relies on the detail. Parts must work together, so some coupling is normal. The goal is to keep it to a few named interfaces instead of details spread everywhere.

The word

Engineers call this

couplingHow much a change in one part of the code forces changes in other parts. Low coupling means you can change one part and the rest keeps working.

Let parts rely on each other only through small, named interfaces. When one change forces edits in many places, pull the shared detail into one place.

Where this idea leads

Skills that encode it

  • code-review Matt PocockFlags Shotgun Surgery, one logical change that forces scattered edits across many files, and says to gather what changes together into one module.
  • codebase-design Matt PocockLocality: change, bugs and knowledge concentrate in one place rather than spreading across callers.
  • blast-radius pstackLooks where grep stops, such as a DB column or JSON another part reads, to find what a change breaks somewhere else.