メシのタネ

メシのタネになる、AIや技術総合情報のサイト


How Far Does This Design Decision Apply?


  1. English
  2. How Far Does This Design Decision Apply?
A navy frame surrounding a tiled plan, with one coral tile outside the frame.

広告

日本語版

“It's an internal API. We can keep the contract loose, right?”

Fair enough. You need to ship, and spending a week on a contract for one caller might be a bad trade. Plenty of teams make that decision and get on with their work.

Then the line comes back a few months later, in a slightly different form.

What did we mean by “internal”?

“Wait, was anything besides the frontend supposed to call this?”

“I thought we agreed this was internal. Was that in Slack?”

“Was Sam even on the team when we decided that?”

Nobody is sure enough to say anyone got it wrong. From the current code, it can be hard to reconstruct the decision at all. The frontend was the only consumer. The same people maintained both sides. Maybe they released together. Those were real reasons to keep the API simple. How many of those conditions still hold?

Decisions have a scope

Most decisions make sense under some set of conditions. They work with this team, this release process, or this level of operational risk. The word “if” is easy to omit because everyone in the room already knows it.

Later a second consumer shows up, or two teams start releasing independently. If the assumptions are missing from the record, the discussion turns into a verdict on the old design. It would be more useful to know which assumption changed.

The facts I want to capture are simple.

  • What did we choose?
  • Which assumptions make that choice reasonable?
  • What case falls outside those assumptions?
  • Who revisits the decision when that case shows up?

A sentence you can actually use

For the internal API, I'd write something like this.

We can change the response shape while the web frontend is the only consumer and ships with this API. Before adding an independently deployed consumer, the API owner will review the contract and agree on a compatibility policy with that consumer.

You now have a boundary and someone to ask. The next team can still choose a light contract. They can also see why the old choice worked and what has to be reconsidered.

An exception makes a decision easier to use. It tells the team when they can proceed on the existing assumption and when they need to have a new conversation. Try asking of the last design decision you made, “What's the first case where this stops working?” If there's an answer, that's probably worth writing down.

Q&A

Do I need an architecture decision record for every small choice?

A sentence in the pull request can be enough. Use a more durable record when multiple teams rely on the decision or when the next person will have trouble finding it in review history.

What if we can't predict the exception?

Write down the supportable assumptions you have today. “One consumer” and “deploys with the API” already give you two things to recheck. You can refine the boundary when the circumstances change.

Is an exception the same thing as a known bug?

An exception here is a case beyond the scope of the decision. If the behavior already fails inside that scope, treat it as a defect or document the limitation explicitly.

Related reading is DRY vs. YAGNI and the cost of abstraction.


コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。