體面編碼之程式碼註釋評論

banq發表於2018-12-31

避免無意義的註釋評論，不新增任何價值。如果透過閱讀程式碼可以清楚地看到某些內容，則評論只會增加噪音。

考慮是否可以改進程式碼，以便不再需要註釋。透過改進命名，重構（例如，提取函式）或引入解釋變數，通常可以解釋解釋程式碼正在做什麼以及有時為什麼的註釋。

考慮一個單元測試是否會更好的溝通。構造良好和命名的單元測試可以解釋程式碼背後的原因，以及在不同情況下演示和驗證其行為。

解釋從程式碼中不清楚的推理。預計未來的維護者可能會對程式碼感到困惑。示例包括邊緣案例處理，必須解決的約束以及效能最佳化。

提請注意令人驚訝的“陷阱”。如果某些事情不直觀或者讓你感到困惑，可能值得注意幫助他人。示例包括看似不合邏輯的業務“邏輯”，以及令人驚訝的庫程式碼行為。

解釋特定“魔術值”的選擇。這些包括框架/伺服器設定，超時，限制，批/池大小，優先順序，快取配置和排序。我們熟悉從程式碼中將這些值提取到常量或配置中，但是經常忽略選擇實際值的原因。在某些情況下，這是在花費大量精力進行負載測試等活動以便選擇適當的值之後。記錄這些內容可以更有信心地進行未來的更改。

突出顯示錯誤解決方法，連結到問題報告。這樣可以在以後修復基礎錯誤（例如庫中）時輕鬆識別和刪除它們。檢視錯誤修復。

記錄程式碼的遠端和斷開部分之間的關​​系。透過程式碼無法顯示這些內容是非常罕見的。它們通常是某種方式的東西，因為遠處的東西（甚至可能在下游系統中）是某種方式 - 例如依賴性或匹配行為。改變一個可以以令人驚訝的方式打破另一個，或者引入使用者體驗的不一致。

寫得清楚，簡潔，明確。遵循這些原則的評論更快更容易理解，有助於避免誤解或混淆。寫作過程通常可以觸發問題的想法或解決方案，就像僅向某人解釋問題可以幫助您提出解決方案一樣。重構不僅適用於程式碼; 寫完評論後，閱讀並考慮是否可以改進。

確保註釋與當前版本的程式碼保持同步和正確。過時或不再適用的評論可能會引起混淆。

遵循專案管理TODO評論的策略。在程式碼中積累這些評論通常表明技術債務和必要工作的累積。這些任務對於專案功能/錯誤工作跟蹤仍然是不可見的，使它們處於被忽視和遺忘的危險之中 - 帶來各種後果。其中一種策略是要求所有TODO在合併拉取請求之前引用問題跟蹤器票證。

相關文章