"Code-Quality"
- Commit message vs source code doc：兩份不同職責的文件
Source code doc 寫給未來讀者、commit message 寫給回顧歷史的考古者。時序敏感的資訊（為什麼這次改、考慮過什麼方案）放 commit、持續適用的契約放 source。配合 git blame 工作流讓考古路徑清楚、source 不必背所有歷史。
- 函式文件分層設計：型別、介面、實作各自該寫什麼
函式文件分層設計：把資訊放在能表達它的最低層次（名稱 / 型別簽章 / 介面 doc / 實作 doc / 範例與測試）、上層留給「下層表達不了的剩餘」。整理各層該寫什麼、容易誤入的內容、配合反模式列表跟寫 doc 前 checklist 收斂出短而精準的文件。
- 型別取代 doc 的收益曲線：強型別語言的 doc 該有多短
型別系統強化等於 doc 表達力轉移——很多 doc 內容應該下移到型別。整理 null safety / enum / wrapper / Result / typestate 各能消除哪類 doc、型別表達不了的剩餘部分（業務動機、性能、副作用、時序）以及收益曲線的邊際遞減點。
- 測試命名作為文件：可執行的規格說明
測試是少數會自我驗證的文件——名稱跟實際行為不符、CI 會炸。把測試命名寫成 state-based / scenario-based / failure-mode 三種模式的 spec 條目、配合 group 結構作為命名空間、讀者跳到測試檔掃名字就能取代讀 doc。