Lesson 17 of 17 · Living With Code You Didn't Write
Architecture Decision Records: Recording the Why
The condition nobody can explain
Somewhere in the pricing code there is a class like this:
<?php
declare(strict_types=1);
namespace App\Reservations\Pricing;
use App\Reservations\Guest;
use App\Reservations\Stay;
final readonly class RatePolicy
{
public function rateFor(Stay $stay, Guest $guest, Rate $rate): Rate
{
if ($stay->nights() > 14 && $guest->countryCode() === 'DE') {
return $rate->withLongStayDiscount();
}
return $rate;
}
}Nobody on the team knows why German guests get a long-stay discount and other guests don't. The person who wrote it left. The ticket it came from is in a project tracker the company stopped paying for. There is no test for it. Deleting it might lose a contract; keeping it might be preserving a bug. So it stays, and every developer who reads the file spends a minute wondering, then moves on.
I've seen a codebase on a project where company IDs from production were used to check whether a feature should do something specifically for that company or not. You can guess why that is a bad idea. The IDs only exist in the production database, so no local or test database has them, and a line like if ($company->id === 4817) doesn't say which company it is, let alone why it gets special treatment. The German check at least tells you who it applies to.
An earlier lesson warned that you'll open your own code with no memory of writing it. The debt quadrant asked "did we know better at the time?", and that question has no answer if nobody wrote down what they knew. This lesson is about the writing down.
Code records the decision, never the reason
Code is a complete record of what the system does and an empty record of why. The if above says exactly what happens to German guests. It says nothing about the partner agreement, the tax rule, the customer request or the mistake that put it there. The reason lived in a Slack thread, a meeting or someone's head, and all three are gone.
The previous lesson showed you reading a codebase from the outside in. The why is the one thing that reading can't recover, because it was never in the code, and it decides whether a rule is safe to change.
Three places to put it
The why goes in one of three places, and each one has a different lifetime and a different reader.
The commit message answers why this change, why now, and what else was considered. It lives forever, attached to the exact lines through
git blame, and you write one on every commit.A comment in the code answers why this line is the way it is, when the code can't say it. It lives as long as the line does and moves and dies with it. You write one when a rule would otherwise read as arbitrary.
A decision record answers why the codebase is shaped this way. It lives for the life of the project, in the repository under
docs/decisions, and you write one when a choice constrains future work.
The commit message
The commit message is the cheapest record you'll ever write, and the one most often wasted on "fix" and "update". Chris Beams's guide to commit messages has seven rules for the shape. The one that matters for maintainability is the last: use the body to explain what and why, not how. The diff already shows how.
Give stays over 14 nights the long-stay rate for German guests
Our German booking partner's contract (2024 renewal, clause 7) requires
the long-stay rate for any guest they refer who stays more than two
weeks. Their referrals all carry the DE country code, and we don't have
a partner id on the reservation yet, so the country is the only signal
we have.
Considered: adding a partner_id column and checking that instead. Held
off because the partner integration is being replaced when they move
to their webhook API (see docs/decisions/0012-partner-referrals.md).Anyone who runs git blame on the if now gets the contract, the reason for the country check, the alternative that was considered, and a pointer to the decision that explains when the shortcut expires. Knowing when it expires is the plan that separates prudent, deliberate debt from the reckless kind.
Two practical points. If your team squash-merges, the squashed commit's body is whatever the merge produces. On GitHub the default is the list of commit messages, so set the repository to use the pull request title and description instead, and write the description with the same care. And a commit message with a why in it is far easier to write on a small commit than on a large one, which is one more argument for small ones.
The comment that explains why
Comments usually describe what the code does, which the code already says. John Ousterhout's rule, from chapter 13 of A Philosophy of Software Design, is that comments should describe things that aren't obvious from the code.
<?php
declare(strict_types=1);
namespace App\Reservations\Pricing;
use App\Reservations\Guest;
use App\Reservations\Stay;
final readonly class RatePolicy
{
public function __construct(
private int $longStayNights = 14,
) {
}
public function rateFor(Stay $stay, Guest $guest, Rate $rate): Rate
{
// Referrals from our German booking partner must get the long-stay
// rate after two weeks (partner contract, 2024 renewal, clause 7).
// We have no partner id on the reservation yet, so the country code
// stands in for it. See docs/decisions/0012-partner-referrals.md.
if ($stay->nights() > $this->longStayNights && $guest->countryCode() === 'DE') {
return $rate->withLongStayDiscount();
}
return $rate;
}
}The comment doesn't repeat the condition. It gives the contract, the reason for the proxy, and where to read more. A reader who needs to change the rule now knows who to talk to and what would break.
Two rules keep why-comments honest. First, the comment lives and dies with the line. When you change the condition, you change the comment in the same commit, and a reviewer who sees one without the other asks. Second, don't write a why-comment for what a name could say. $this->longStayNights doesn't need a comment explaining that fourteen is the long-stay threshold, because an intent name already says it.
The decision record
Some reasons are bigger than a line. Why the domain code doesn't import Eloquent. Why money is stored in integer minor units. Why the partner integration is being replaced. These are the constraints that shape a whole area of the codebase, and a new developer will bump into them as soon as they start and ask why.
Michael Nygard's 2011 post "Documenting Architecture Decisions" introduced a format for this: one short markdown file per decision, numbered, in the repository, with a title and four sections.
# 12. Identify partner referrals by country until the webhook integration ships
Date: 2026-03-02
## Status
Accepted
## Context
Our German booking partner refers guests through a nightly CSV import.
Their contract requires the long-stay rate for referred guests staying
over 14 nights. Reservations have no record of which partner referred
them; the import only sets the guest's country code. The partner is
moving to a webhook API, and the import will be retired with it.
## Decision
Until the webhook integration ships, identify partner referrals by the
DE country code in the rate policy. Do not add a partner_id column for
the CSV import; add it as part of the webhook work, where the id will
actually be available.
## Consequences
Every German guest staying over 14 nights gets the long-stay rate, referred or not. Finance
has accepted the over-discount for the interim. The rate policy carries
a comment pointing here. When the webhook integration lands, the
country check must be replaced with a partner id check and this record
superseded.A record isn't rewritten when the decision changes. A new record supersedes it, and the old one's status is changed to point at the new one. Nygard's reason: "It's still relevant to know that it was the decision, but is no longer the decision." That is why the folder reads as a history: you can go through the decisions in order and watch the codebase's reasoning develop, including the decisions that turned out wrong.
Keep the records next to the code, in the repository, so they are versioned with it and show up in the same search. A wiki page rots because nobody opens it when they change the code. A file in docs/decisions shows up in the diff.
What earns a record
A why for every line would bury the ones that matter. Write one down, in any of the three places, for:
A shortcut taken on purpose. The plan is what makes prudent, deliberate debt healthy, and a plan nobody wrote down leaves with the person who made it.
A rule that would read as arbitrary to someone without the context. The German guests, the fourteen nights, the one customer whose special case became a column.
A choice between two reasonable options. The next person will wonder why you didn't pick the other one, and without a record they may switch to it and hit the problem you avoided.
A constraint from outside the codebase. A contract, a regulation, a limit in a partner's API, a promise made to a customer.
Things the code says plainly don't need a record. Neither does the reasoning behind a widely known practice; link the reference instead.
Tests as records
A test with a good name is a record that fails loudly when the rule changes. german_guests_get_the_long_stay_rate_for_stays_over_fourteen_nights states the rule in one line and enforces it. The cost-of-change lesson listed tests that describe behaviour among the things that flatten the curve, and this is part of the reason: the test carries the rule's intent forward in a form that can't quietly go stale.
The test records that the rule exists and what it is, not where it came from. The three records above give the origin. Together they mean the rule can be changed on purpose and not by accident.
In code review
When a change adds a condition that can't be explained from the code alone, the reviewer asks: where is the why? The review is the last moment the author still has the context in their head. Days later it is gone, and the answer becomes a conversation in Slack that the next reader will never find.
The one thing to remember
The code records every decision and none of the reasons. The reasons are what the next reader needs in order to change the code safely, and they are cheapest to record at the moment they are made: a body on the commit, a comment where the code can't speak for itself, and a short decision record when the choice constrains the future. Without them, every rule is either sacred or suspect.
Exercise
Run
git blameon the strangest condition you know of in a codebase you work in. Read the commit message. Does it tell you why?If it doesn't, find out. Ask whoever has been there longest. Then write the why into a comment on that line, and open a pull request with the reason in the body.
Take the most recent decision your team made that constrains future work. Write it up as a decision record using the format from this lesson and put it in the repository.
Related Links
- Documenting Architecture DecisionsMichael Nygard's original post introducing the decision record format.
- Decision record template by Michael NygardThe template, ready to copy.
- How to Write a Git Commit MessageChris Beams's seven rules, including "use the body to explain what and why vs. how".
- A Philosophy of Software DesignChapter 13, "Comments Should Describe Things that Aren't Obvious from the Code".
- Configuring commit squashing for pull requestsGitHub's settings for the default squash commit message, including the pull request title and description.
- ADR GitHub organizationTooling and examples for keeping decision records in a repository.