コードを書く前にアーキテクチャを書き出す
一ページの文章は半日で書けて、放っておけば三週間後のプルリクエストで決着することになる議論を先に片づけます。
下書きです。この記事はレイアウトの骨組みとして記事セクションに同梱されており、本文が入るまで検索とサイトのアシスタントからは除外されています。
この記事は英語で公開しています。サイトの他の部分は翻訳していますが、記事は翻訳していません。技術的な論旨は機械翻訳を通すより、書かれた言語のまま読むほうが価値が高いからです。
The argument against writing the design down is always speed. It is a bad argument, because the alternative is not "start sooner"; it is "discover the disagreement later, in code, when reversing it is expensive".
What the document is for
Not the diagram. The diagram is the easy half and the half that gets shown. The useful part is the paragraph under it explaining which parts genuinely need a model and which parts are better off deterministic, because that is the decision the whole system is downstream of.
What it is not for
It is not a specification to be followed to the letter, and treating it as one produces the padding that a technical reader notices immediately. It is a record of what was decided and why, so the next person, who is often you, can tell the difference between a considered choice and an accident.
This post is a placeholder shipped with the writing section. Replace the body with the real piece; the frontmatter above is the only thing the site reads.