工程原則 是做什麼的?
建立最小且正確的解決方案,並保持其可理解且易於安全變更。將原則視為推理的工具,而非凌駕於需求、儲存庫慣例或證據之上的法則。
工作循環
- 建立契約。 閱讀相關程式碼、呼叫端、測試與儲存庫說明。辨識必要的行為、輸入、輸出、不變量、失敗模式及相容性約束。區分觀察到的事實與假設。僅在未解決的需求會實質改變解決方案時才提問。
- 選擇比例適當的設計。 重複使用本地模式與現有功能。偏好直接實作;僅在該處包含真實複雜性或保護實際邊界時才加入結構。考慮變更所觸及的安全性、資料完整性與資源限制。
- 一次只變更一個關注點。 保持 diff 的內聚性。保留不相關的工作。將保留行為的重構與有意的行為變更分開,使每個部分都可審查。修復根本原因,而非僅僅觀察到的症狀。
- 驗證所承諾的行為。 使用最狹義但有意義的測試或可執行場景,包含相關的失敗路徑。檢查實際執行過的內容;空的測試選擇證明不了什麼。通過的測試僅是對其所斷言的路徑與斷言的證據,而非所有正確性或相容性的證明。
- 完成變更。 更新受影響的呼叫端、契約與文件。移除因本次變更而過時的程式碼。簡要報告結果、驗證與任何剩餘的限制;僅在原則實質影響決策時才解釋其理由。
根據風險調整此循環的規模:本地重新命名無需太多儀式;共享 API 或持久資料變更則需要消費者與遷移的證據。不要為例行編輯製造設計文件或專家鏈。
除錯與儲存庫工作流程
將使用者回報的失敗視為可重現的案例;不要要求他們僅為確認而再次重複。將觀察到的行為與假設分開,然後收集能區分可能原因的證據。使用聚焦的重現、目標檢查或除錯器,而非靠猜測更改程式碼。修復根本原因,保留有用的診斷資訊而不洩露機密,且絕不能為了讓路徑看起來成功而壓制錯誤。當失敗可能留下部分狀態時,加入缺失的回歸覆蓋並驗證相關的復原行為。
使用儲存庫現有的建置、測試、執行與生成入口點。閱讀它們文件化的前置條件,並執行與人類和 CI 相同的指令;不要引入第二套工具鏈,或在儲存庫已有其他合適介面時要求使用 Make。沒有匹配測試的測試指令並非證明。
維護有用的貢獻者文件:保留程式碼本身無法說明的理由、不變量與關鍵流程;更新受影響的文件,根據讀者選擇使用者參考資料、教學或疑難排解材料。避免與變更無關的廣泛文件重寫。
設計原則
正確性始於契約
在選擇模式之前,定義必須保持為真的條件。使用適當的型別、建構子和明確的狀態轉換,使無效狀態難以表達。保持可變狀態的擁有權與資源生命週期的清晰。
在邊界處驗證不受信任的輸入。不要僅因看起來像防禦性程式碼就移除檢查:要確認該條件是不可能發生、已獲得保證,還是仍為真實的失敗模式。保留有用的錯誤上下文,但不洩漏機密。絕不能將失敗變成虛構的成功結果。
簡潔性:KISS 與 YAGNI
KISS 意味著最小化維護者必須理解的複雜度,而非僅是程式碼行數。YAGNI 意味著實作目前的需求,而非推測中的未來功能。兩者都不能作為忽略錯誤處理、不安全儲存或無法維護的捷徑的藉口。
避免沒有當前需求的插件、通用框架、設定層或擴充點。簡單的設計仍然可以有清晰的邊界,使將來的變更成本低廉。
系統中的複雜度
區分本質複雜度(問題本身所固有)、可選複雜度(有代價的能力)與意外複雜度(實作指定行為時可避免的困難)。使用這些作為推理類別,而非功能配額。將它們應用於實作、介面、整合以及使用者的努力與錯誤風險:降低某處的成本可能會將其轉移到別處。移除意外複雜度;當可選能力的使用者價值能證明其全生命週期成本合理時,保留它。在截止日期前,比較當前的交付價值與端到端的努力、支援與維護;較少的行數或功能本身並不能證明總成本較低。範例請參閱 複雜度、介面與效能。
內聚性、耦合性與資訊隱藏
將因相同原因而變更的程式碼分組;將獨立變更的關注點分離。將易變的實作選擇隱藏在一個小而內聚的介面之後。偏好能完成有用工作的深層模組,而非一串傳遞包裝器。
當某個共享機制能服務於可識別的呼叫者,且不嵌入任一呼叫者的政策時,介面可以是某種程度的通用。保持其通用性不超過當前使用所證明的範圍:猜測的未來需求可能會加重當前呼叫者的負擔。當契約確實是特定時,選擇專用介面。
單一職責關注的是變更的內在原因,而非每個類別一個方法。低耦合意味著消費者只需要很少的內部知識,而非每次呼叫都需要一個介面。保持依賴方向明確,並在實際可行時避免循環。
抽象化與 DRY
DRY 意味著每一份知識都有單一的權威表述,而非消除每一個看起來相似的序列。當呼叫者表達相同的規則且應共同演化時,共享邏輯。當表面相似的程式碼屬於不同的概念或生命週期時,保持它們分離。
當知識也出現在生成檔案中時,辨識其權威來源與產生器。在重新生成前保護無關的編輯;解決重疊的擁有權,而非覆蓋使用者工作。更新來源,執行現有的產生器,並檢查產生的 diff。不要手動編輯產生的輸出作為持久的修復,也不要為微不足道的工作添加生成機制。
在提取之前,識別共享的契約、預期的變更原因以及抽象化所移除的複雜度。不要使用數值重複閾值作為證據。少量的重複其成本可能低於錯誤的耦合。
SOLID 作為診斷問題
在設計獲益時使用這些問題;不要將物件導向架構強加於程序式或函數式程式碼。
- 單一職責: 此單元是否混合了獨立變更的關注點?
- 開閉原則: 是否存在一個經過證明的變異軸線值得隔離,而非一個假設性的擴充框架?
- 里氏替換: 一個實作能否取代另一個,而不透過更強的前置條件、更弱的保證或不相容的失敗來驚嚇呼叫者?
- 介面隔離: 消費者是否僅依賴他們實際使用的功能?
- 依賴反向: 穩定的政策是否應依賴於狹義的契約,而非易變的 I/O 細節?函式或參數可以提供這個接縫;類別層次並非必要。
當繼承並非建模真正的可替換關係時,偏好組合勝於繼承。使用語言慣用的機制,而非將模式名稱作為目標。
可讀性與最小驚訝原則
選擇能揭露領域意義、單位和擁有權的名稱。保持控制流程與副作用易於理解。使用註解來解釋理由、約束和非顯而易見的保證,而非敘述明顯的陳述。
遵循儲存庫慣例,除非它們造成具體問題。函式大小、參數數量與巢狀深度是警告信號,而非通用數值限制。額外的間接層並非自動代表更乾淨的程式碼。註解可以保留理由、約束以及程式碼本身無法說明的抽象化;根據上下文判斷其價值,而不是為了達到長度或註解數量規則而移除它們或拆分內聚的邏輯。
依賴性與效能
對於困難且成熟的既有功能,尤其是密碼學和通訊協定處理,重用一個有維護且合適的程式庫。評估適用性、安全性、授權、相容性、營運成本與依賴負擔。不要為語言或儲存庫已提供的簡單操作添加依賴。
為預期的輸入規模選擇合理的資料結構與演算法。避免明顯的重複工作和浪費的分配或複製。在複雜的最佳化之前測量可疑的瓶頸;對代表性的工作負載進行基準測試並保護正確性。命名工作負載、指標、基線、目標與停止標準;使用與實際使用者或系統結果相關的度量,而非活動計數。一旦契約達標,或進一步的收益不值得增加的複雜性與維護時,就停止。決定契約看重的是延遲、吞吐量還是資源使用:批次處理可以提升吞吐量,但會惡化回應時間。不要為了風格上的簡潔而犧牲已陳述的延遲或記憶體需求。範例請參閱 複雜度、介面與效能。
Unix 哲學實務
編寫內聚的元件,做好單一工作並透過明確的契約進行組合。這不要求每個功能一個程序、微服務、純文字儲存或到處無狀態。具有清晰 API 的內部程式庫同樣可以組合。
- 將機制與政策分離。 在能降低耦合的情況下,保持可重複使用的計算獨立於呈現、環境以及不斷變化的商業選擇。
- 為組合而設計。 避免隱藏的全局狀態和不必要的硬編碼路徑。使依賴和副作用明確;在適當情況下讓呼叫者選擇目標。
- 偏好可檢查的表示法。 使用簡單的資料結構和文件化的格式。文字對於可互操作的工具有價值;當忠實度、數量或效能要求時,二進位格式是有效的。
- 保持正常運行安靜,失敗可見。 靜默表示沒有不相關的雜訊,而非缺少結果資料或壓制診斷資訊。
- 重用工具。 偏好使用現有的可靠功能,而非重建它們。保持自動化在為腳本設計時為非互動式。
根據人類和機器消費者選擇介面風格,而非傳統。函式或程式庫 API、穩定的 CLI 或篩選器適合機器呼叫者和可重複的工作;人類任務可能需要可發現性、回饋或直接互動。如果兩者都是真實的消費者,將領域邏輯與可選的包裝器分離,使它們共享行為,而不使 GUI 成為強制。遵循滿足契約的最簡單風格。參閱 Unix 介面 和 複雜度、介面與效能 以了解實際取捨。 關於 CLI、管線和設定設計,請閱讀 Unix 介面。當複雜度、介面風格或效能取捨實質影響決策時,請閱讀 複雜度、介面與效能。關於衝突的原則與範例,請閱讀 取捨。這些參考資料是條件式的;對於不相關的本地編輯,沒有什麼是強制性的。 關於實際除錯、專案指令、生成的工件、維護者文件和依賴評估範例,請閱讀 除錯與維護。
安全的演化與驗證
重構保留可觀察的行為,包含輸出、錯誤、副作用以及消費者依賴的契約。不要在重構期間默默修復怪癖。有意義的契約變更應明確更新受影響的測試和消費者;被取代需求的測試並非永久的限制。
以行為導向的測試保護公開邊界。重用足夠的覆蓋率;當重要路徑未受保護時,添加回歸或特徵化測試。在實際可行時偏好真實實作或聚焦的假物件,但使用測試替身來隔離真正昂貴、不確定或不安全的邊界。避免關於私有方法呼叫或確切原始碼措辭的斷言,除非這些本身就是契約。
檢查有意義的邊界情況:格式錯誤的輸入、空資料、資源失敗,以及在相關時的併發或部分寫入。不要為每一次編輯規定任意的覆蓋率百分比或完整的測試套件。
除非變更範圍包含公開相容性的變更,否則保持其不變。對於持久契約和持久資料,檢查消費者、部署順序、遷移和復原。當舊版和新版必須共存時,使用擴展/收縮或其他階段性方法;否則,協調的原子變更可能就足夠了。不要沒有實際需求就移除復原路徑或安裝相容性墊片。
最終決策檢查
在宣布完成之前,詢問:
- 實作是否滿足實際契約,包含相關的失敗?
- 每個抽象化、依賴項和變更的檔案是否都由這個任務證明合理?
- 維護者是否能找到規則、其狀態擁有者以及保護它的證據?
- 我是否保留了現有行為,或是在受影響的消費者中明確表明了意圖中的變更?
- 我實際驗證了什麼,還有什麼尚未驗證?
私下使用此檢查;不要為每次編輯發出模板化報告或原則評分。