Peter Sommerlad

程式碼是唯一的真相來源#

程式的**最終語意（ultimate semantics）**由其執行中的程式碼決定。原始碼是我們最能直接檢視的東西，因此當你閱讀原始碼時，程式的意義應該一目了然。

其他文件都可能不完整或過時：

• 最精確的需求文件也不會包含程式實際行為的完整故事
• 設計文件可能捕捉了計畫中的設計，但缺乏實作的必要細節
• 這些文件可能已經與當前實作失去同步，甚至從未被撰寫過
• 原始碼可能是僅存的參考

註解不等於真相#

你可能會說：「我的註解會告訴你一切。」但請記住：

• 註解不是可執行的程式碼，它們可能和其他文件一樣出錯
• 一直以來有一種傳統認為註解無條件是好事，導致有些程式設計師不加思考地寫大量註解
• 重複程式碼已經表達的內容，或解釋顯而易見的事情，反而是錯誤的方式
• 冗長的註解會佔據螢幕空間，甚至被 IDE 自動隱藏

如果程式碼需要註解來解釋，考慮重構它，讓它不需要註解。如果需要解釋某次變更的原因，請寫在版本控制系統的 check-in message 中，而不是程式碼裡。

如何讓程式碼自己說真話#

• 使用好的命名：選擇能清楚表達意圖的名稱
• 以內聚性為原則組織程式碼：好的命名也因此更容易
• 解耦程式碼：達到正交性（orthogonality）
• 撰寫自動化測試：解釋預期的行為並檢查介面
• 無情地重構：當你學會更簡潔、更好的解法時
• 讓程式碼盡可能簡單易讀

像創作一樣對待程式碼#

把程式碼視為一首詩、一篇散文、或一封重要的信。精心雕琢你的表達，讓它清楚傳達自己在做什麼，即使你已不在場，它仍能傳達你的意圖。記住：有用的程式碼被使用的時間往往比你預期的更長。維護程式設計師會感謝你的。