Write down why

Think of it when you make a choice that a newcomer would question, and changing it later would cost a lot.

In everyday life

Like a note taped inside a fuse box: “Circuit 4 runs alone because the old oven kept tripping the kitchen.” Without the note, the next electrician tidies it up.

One case

Two years ago, an airline booking site’s team chose to store fares as whole cents with one written rounding rule, because floating-pointThe way most programming languages store numbers with a fraction. Many amounts, such as 0.10, are stored only approximately, so sums can be off by a tiny bit. amounts gave rounding errors in tax. Nobody wrote down why. A new developer sees the cents, thinks they are odd, and changes the refund code to floating-point dollars. Refunds start coming out one cent short, and the team spends a week finding the old reason again.

Write down why
The ideaGuard the doors
Write down why

A short note that says what was decided, why, and what else was considered. Write one when a choice is hard to reverse, would surprise a future reader, and was a real trade-off.

Guard the doors, Habits

Every case

Code shows what was decided, never why. The reason lives in someone’s head or an old chat, and both fade. Without it, the next person sees an odd choice, takes it for a mistake and undoes it, or is afraid to change anything at all. A decision record keeps the why next to the code, and engineers often call it an ADRArchitecture decision record: a short note in the repo on one hard-to-reverse choice and the reasons for it.. Writing one also makes you name the alternatives, which often shows a weak choice before it is built. Keep them rare: a record for every small choice buries the ones that matter.

The word

Engineers call this

decision recordA short note that says what was decided, why, and what else was considered. Write one when a choice is hard to reverse, would surprise a future reader, and was a real trade-off.

When a choice is hard to reverse, surprising, and a real trade-off, write down what you chose and why. Skip it for everything else.

Where this idea leads

Skills that encode it

  • domain-modeling Matt PocockOffer an ADR only when all three hold: hard to reverse, surprising without context, and the result of a real trade-off.
  • grill-with-docs Matt PocockWrites decision records during the plan interview, as each choice settles.
  • why pstackDigs the reason behind code out of history, PRs, tickets and chat, for the cases where nobody wrote it down.