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

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

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

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

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

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

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

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

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

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

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

說到底，技術好的大佬才擁有評論註釋的權利！

那麽開發一至五年的程序員，技術雖然遇到了瓶頸，但是你又拒絕平庸，期待蛻變，想進入一線互聯網公司或者給自己漲薪。我這裏剛好有一套自己保存的Java進階學習資料。包含了Spring框架、Mybatis框架SpringBoot框架、SpringMVC框架、SpringCloud微服務、Dubbo框架、Redis緩存、RabbitMq消息、JVM調優、Tomcat容器、MySQL數據庫等等。

資料領取方式：加入粉絲群963944895，【點擊加入群聊】，私信管理員即可免費領取

阿裏架構師淺析體面編碼之代碼註釋評論