Tech Design Review: 軟體架構設計審查

（2021–02–25 update. 原標題：軟體工程師的架構設計 EP1. 從幻想到實作的團隊分享）在產品開發的流程中，藉由分享實作前的技術架構設計，讓團隊先體驗一遍，提前找出可能的驚奇與意外、進行對實作計畫的討論，不但更容易避開最後一刻因為技術問題才來改規格與實作的災難，還能促進團隊對整個實做的了解，pull request 也更容易被 approve 了。

好像不時就會在新聞上看到，做到最後發現規格外的問題、同事的技術回饋最後已經因為做完改不動，甚致無法符合當初訂好的 spec 需求等等情況。

四個好理由：審查可改善時程績效、審查可去除多餘的工作、審查可彌補測試的不足、而且審查可以提供訓練。－－《溫伯格的軟體管理學｜第２卷｜第一級評量》第十八章【以審查做為評量的工具】p.441

（註 1）

先分享就近三四個專案實行的一些效益

1. 專案 A 在分享時發現遺漏了一個重要情境。
2. 專案 B 討論到資料模型的欄位與關聯，在實作資料庫的 migration 之前就能先取得回饋，省了之後再來好不想改的力氣。
3. 專案 C 做完架構設計後發現規格因某個外部關鍵因素而需要重新設計，幸運地免了 revert code 甚至上 hotfix 的心力損耗。

不只以上，許多很棒的架構設計經驗現正持續發生，其最重要的目的：提前溝通並發現驚奇或缺漏，可預期帶來正向的品質確保。

軟體工程師的洞見與經驗

基本期待是三至五年經驗的工程師，能提出一個可以進行關鍵討論的架構設計，也建議不論年資總是找一個在這件事情上可信任的人幫忙校閱，如同每一個 pull request 或每一本書釋出之前都應該有人幫忙看過，提供自己大腦一個對話的空間。也可以不論團隊大小，一個人在白紙上花十幾分鐘也勝於悶著頭做了好幾天後才想到驚奇與意外；有時找個人聊聊都勝於無。

還缺心法的話，可見本系列第一篇由我同事 David Lee 寫的【架構設計 EP0.從無到有的腦內脈絡】，提供了一個易於開啟思路辨證的樣版。

在不同的時機與階段，選個最有效益的時間點

用一個過度簡化的階段來示意：

0. 組織使命
1. 商業目標
2. 產品設計
3. 功能開發：寫 code 與 test

理想大約在 3 之前，2 之後或之中，若在有產品規格 50% ~ 100% 時提前丟出來，可能幫助自己與產品設計師更早釐清並溝通規格；規格明確的話等正式開始再來做也 OK。

正式分享的會議時機，建議在 spec kickoff 跟大家過完之後，以免變成對 UI 設計或規格的討論與釐清大會。若時機尚末完備可要求延後。假如主要是實體會議也建議主講人在現場，以應對預期的超大量資訊頻寬溝通。

寫程式大約只佔總時程的六分之一而已，隨便一點點估計或比例上的誤差，就可能使推導出來的結果有天壤之別。－－《人月神話》第八章【預估】p.123

目標分享對象：人啊

主要目標雖是同專業團隊的成員，能讓不同團隊成員能理解的話，也更容易達到溝通與讓每個人體會的效果。也可能邀請同專案團隊的工程師或能參與技術架構討論的專案成員參加。

架構設計的要點

【沒有完美或理應完美的設計系統】：設計者經常受限於一條立意良好的錯誤信念，那就是好的解決方案應該完美無缺、條理分明，可以把所有設計問題毫無例外的含括進去。－－《建築的法則》77 p.171

點出相關重要的溝通事項，想要多附也很棒，只要資訊在這裡對參與的人而言有意義夠清晰明白。例如：

• 情境、大綱、鳥瞰、商業邏輯面的過程流：讓參與者能容易進入的前情摘要（Overview），通常跟專案目標與設計師提供的流程文件直接關聯。
• 關鍵問題、決策與原因：例如需填寫 Problem Statement 及 Proposed Solution。同樣儘可能清楚明白地描述問題並指出關鍵的細節。
• 風險評估：專案時程風險與上線時可能發生的問題與 B 計畫，有的話也應當分享。許多情境都可以有各階段失敗的規劃。
• 成功的標準（Success Criteria）：當這個架構完成時，會發生什麼事，例如用兩三個句子描述，可能包含相關可量化的指標。
• 範籌（Scope）：哪些是先決條件、必要的，哪些不是。

技術架構面的資訊流

最近團隊剛結束《Clean Architecture》的讀書會，就是在講資訊架構怎麼流。可預期 API schema 與 DB model 常常是各端架構的關鍵之一。

例如 ORM 裡的 Model，與其關聯可以表示了核心資料結構的長相，而 API schema 文件可描述資料的流向與變動，對應著他們想要完成的商業邏輯。在確定架構的過程中可以先試寫個純文字版的 API 長相來與前後、行動開發端討論，如同 GraphQL 的 schema 或 REST 的 Swagger 都是從歷史經驗所產生的最佳實踐：先把溝通介面訂好，大家就可以各自散開工作了，不用等，也不用到專案後期才發現怎麼 API 對接的欄位與作用不是這樣。

第一件事就是流（flow）…（略過）…重點是機構裏的每一個人都很容易就看懂過程流所程述的。…（略）…圖的本身不重要，圖的繪製過程才重要。－－《溫伯格的軟體管理學｜第２卷｜第一級評量》第四章【讓過程看得見】p.116

要做到多廣多深，需要多正式？

重點是與同專業與同專案的夥伴溝通到要點，即使對他們而言關鍵點可能在文件的不同地方。（註 2）也避免把 80% 精力花在格式、形式或架構文件的程序上而只剩 20% 的力氣來寫好關鍵的要點。

架構設計的結果

或許期待結果總是被接受，然而真正有效的成果應該是反映真實的情況。溫伯格的書中也列出來值得考慮的五種結果：

1. 接受
2. 接受些微的修正（不必再一次討論）
3. 需要重大修改（並再次討論）
4. 需要重做（並重新討論）
5. 未完成：包含有人缺席、參與者未做好準備、時間不夠、內鬨，提供的資料無法審查也是有可能的。

【好的建築師懂得隨機應變，迅速調整。】：隨著設計工作推進，結構發生問題、客戶變來變去、消防逃生通道很難解決，方案細節忘了又發現了，對先前的資訊有了新的理解等。…（略）…會把「parti」（建築物的核心構想或概念，註 3）的失敗當成一項有益的暗示，進而針對失敗的地方提出更好的計畫。－－《建築的法則》26, p.69

總結：分享設計提升產品與工程能量，遠離最後才發現驚奇的失敗

這件事從小做起就很有效益，設計與分享本身就是最好的學習與訓練。溫伯格說（註 4），幾乎所有的失敗專案，都可歸於以下兩種原因：１．資訊失敗。２．行動失敗。而他系列書的第１、２卷都在處理資訊失敗的主題，也是這裡架構設計想要處理的議題：

• 不知道人們想要什麼產品 <- 這點看似與架構設計沒那麼相關？但結果是需要重做時就太相關了。
• 不了解流程的本質
• 沒有顯而易見的進展證據
• 缺乏足夠的穩定性做有意義的評量
• 缺少或失去設計完整性

身為進擊的工程師，現在就去探尋大海的秘寶吧例如 iCHEF 持續召募中，別再等了。然後記得先（請航海士？）畫個航海圖帶著。

延申閱讀

本文雖是個簡化的起點參考，也別被溫伯格一系列讀不完的書嚇到了，以下是更多參考可以備著：

1. 為什麼要有工作手冊…《人月神話》第七章【巴別塔為什麼會失敗】p.109
2. 《Code Complete, Second Edition》第三章【三思而後行：前期的前置作業】、第四章【關鍵的「建構」決策】，與第五章【軟體建構中的設計】
3. 有關組織學習的關鍵問題，並非如何去做，而是在哪裏發生－－《Peopleware》第 32 章【組織學習】p.274
4. 知識、技能、判斷、知識管理－－《專業致勝》第五章【專業服務公司的智慧資本】p.131

註

1. 這邊指的「架構設計」在溫伯格的書中有點像「技術審查（Technical Review）」，不同的是在執行上完全以溝通與探索技術實作的最終模樣為目的，通常沒那麼正式。 不會用來宣誓說就是這樣做，也不會要求每一位參與者畫押。
2. 《Code Complete, Second Edition》一書中在第五章【軟體建構中的設計】（p.118）提到的許多因素，可以想像愈高的安全性與穩定性需求，會需要愈細的規劃與愈正式的文件與程序。有趣的是它不只討論「開始建構之前的設計所需的細化程度」，還包含了「文件正規程度」。
   Design Formality and Level of Detail Needed, Code Complete, Second Edition
   https://learning.oreilly.com/library/view/code-complete-second/0735619670/ch05s04.html#how_much_design_is_enoughquestion_mark
3. 《建築的法則》15 p.47：「建築師可以用多種方式來表達其核心構想（parti），但最常見的做法是，畫出整棟建築物的平面配置構想圖，以及其中所暗示的經驗感性與美學感性（experiential and aesthetic sensibility）。…（略）…案子不同，對各項要素的關注比例也就不同」
4. 《溫伯格的軟體管理學｜第４卷｜擁抱變革》第十一章【穩定軟體工程的構成要件】