重點摘要#

• 記錄架構決策背後的**理由（rationale）**是最值得投資的文件類型之一
• 文件應回答「我們做了什麼決定？」和「為什麼這樣決定？」
• 這類文件不會隨程式碼改變而過時，且所需的努力極小
• 記錄過程迫使你驗證自己推理的嚴謹性

詳細內容#

軟體開發社群對文件的價值爭論不休，尤其是關於「大型前期設計」的價值和維護設計文件與不斷變化的程式碼同步的困難。

為什麼要記錄決策理由#

軟體架構的本質就是在各種品質屬性、成本、時間等因素之間做權衡取捨。應該清楚地讓你的管理者、開發者和其他利害關係人知道：

• 為什麼選擇了某個方案而非其他方案
• 做了什麼取捨（例如：犧牲水平擴展性以降低硬體和授權成本？為了資料加密而接受整體回應時間增加？）

文件格式#

格式可以根據專案需求靈活調整，從快速筆記、wiki、部落格到更正式的範本都可以。無論選擇什麼格式，文件應該：

• 回答「我們做了什麼決定？」
• 回答「為什麼這樣決定？」
• 記錄「考慮了哪些替代方案？為什麼被否決？」
• 具備可搜尋性，以便需要時能輕鬆找到

文件的用途#

• 作為向開發者溝通重要架構原則的手段
• 當開發者質疑架構邏輯時，幫助團隊達成共識
• 向管理者和利害關係人解釋軟體為何如此建構
• 在專案交接時提供脈絡（你有多少次繼承了一個系統卻完全不理解設計者的想法？）

記錄理由最重要的好處是：它迫使你明確地表達推理過程，以驗證你的基礎是否穩固；同時它可以作為重新評估決策的起點，當影響最終決定的條件發生變化時。

— By Timothy High