整潔代碼之道 4 註釋

還是認爲這一章中作者對於註釋的態度有點過於理想了，所以內容僅供參考

Tips

1. 若編程語言足夠有表達力，或者我們擅長用這些語言表達意圖，就不那麼需要註釋，也許是根本不需要
   • 我認爲，如果註釋能夠清晰的表達代碼的含義，對於回顧一些過去的項目是非常好的
2. 註釋的恰當用法是彌補我們再用代碼表達意圖時遭遇的失敗
3. 註釋常常會與其所描述的代碼分隔開來，越來越不準確
   • 所以在維護代碼的同時，也要相應的維護註釋，防止註釋和代碼被分隔
4. 程序員應當負責將註釋保持在可維護、有關聯、精確的高度

4.1 註釋不能美化糟糕的代碼

1. 帶有少量註釋的整潔而有表達力的代碼，要比帶有大量註釋的零碎而複雜的代碼像樣的多

4.2 用代碼來闡述

1. 很多時候，只需要在函數名稱上講功能描述清楚，就可以省去一段註釋

4.3 好註釋

1. 有些註釋是必須的，也是有利的

4.3.1 法律信息

1. 公司代碼規範要求編寫與法律有關的註釋

4.3.2 提供信息的註釋

1. 用註釋來提供基本信息

4.3.3 對意圖的解釋

1. 註釋不僅提供了有關實現的有用信息，而且還提供了某個決定後面的意圖

4.3.4 闡釋

1. 註釋把某些晦澀難明的參數或返回值的意義翻譯爲某種可讀形式

4.3.5 警示

1. 用於警告其他程序員會出現某種後果的註釋

4.3.6 TODO 註釋

1. 用 // TODO 形式在源代碼中放置要做的工作列表
   • 例如某個代碼結果中打算做到某個擴展，但是現在沒做
   • 按照現代 IDE 的功能，在每次提交代碼時，都會給予提示

4.3.7 放大

1. 註釋可以用來放大某個看來不合理之物的重要性

4.3.8 公共 API 中的 Javadoc

1. 沒有什麼比被良好描述的公共 API 更有用和令人滿意了

4.4. 壞註釋

1. 都是糟糕代碼的支撐或藉口，或者是對錯誤決策的懶散修正，基本上都是這類程序員的自說自話，沒有什麼效果

4.4.1 喃喃自語

1. 如果你決定寫註釋，就要花必要的時間確保寫出最好的註釋
2. 任何迫使讀者查看其它模塊的註釋，都是懷註釋

4.4.2 多餘的註釋

1. 讀註釋花的時間比讀代碼花的時間還要長

4.4.3 誤導性註釋

1. 對代碼描述不夠精準

4.4.4 循規式註釋

1. 所謂每個函數都要有 Javadoc 或每個變量都要有註釋的規矩完全是個笑話

4.4.5 日誌式註釋

1. 在每次編輯代碼時，都在模塊開始處添加一條時間註釋，這個已經沒必要了，因爲現在都有 代碼版本控制系統（ Git ）

4.4.6 廢話註釋

1. 對於顯而易見的事喋喋不休，毫無新意

4.4.7 可怕的廢話

1. Javadoc 很有可能是廢話

4.4.8 能用函數或變量時就別用註釋

1. 有時候爲了把代碼寫的簡潔，而進行了很長的嵌套，但是又擔心別人看不懂，所以加了一些註釋
2. 這樣的做法其實是本末倒置，不如直接把代碼拆分出來寫清楚

4.4.8.1 Bad Example

// 描述了下面這串代碼的作用
if (smodule.getDependSubsystems().contains(subSysMod.getSubSystem())) { … }

4.4.8.2 Good Example

1. 將代碼拆分後，層次變的更分明，更容易理解，註釋也顯得無關緊要了

ArrayList moduleDependees = smodule.getDependSubsystems();
String ourSubSystem = subSysMod.getSubSystem();
if (moduleDependees.contains(ourSubSystem)) { … }

4.4.9 位置標記

1. 儘量少用標記欄，只在特別價值的時候用

4.4.10 括號後的註釋

1. 如果發現自己想標記右括號，這就說明應該縮短函數，將這一段代碼遷移到外部，單獨作爲一個函數在引入此處

4.4.11 歸屬和署名

1. 代碼版本控制系統非常善於記住 誰在何時添加了什麼
2. 沒必要用那些各種格式的註釋搞髒代碼
3. 代碼版本控制系統纔是這類信息最好的歸屬地

4.4.12 註釋掉的代碼

1. 直接把代碼註釋掉是非常噁心的做法
2. 可能當時你從某處複製過來一整段業務代碼，但你只需要其中一部分，對於不需要的那些，暫時也沒法確定以後需不需要（極大可能是因爲懶得思考）
3. 首先從其他地方複製整段代碼就不是一個好兆頭，其次如果非要複製，請一定搞清楚用途，留下需要的，刪掉多餘的，而不是註釋多餘的

4.4.13 HTML 註釋

1. 源代碼註釋中的 HTML 標記是一種廢物

4.4.14 非本地信息

1. 請確保註釋描述了離它最近的代碼
2. 不要在本地註釋的上下文環境中留下完全不相干的信息

4.4.15 信息過多

1. 別再註釋中添加無關的細節描述，沒人有耐心去看完整段整段的註釋內容
2. 註釋應該保持簡潔的風格

4.4.16 不明顯的聯繫

1. 註釋及其描述的代碼之間的聯繫應該是顯而易見的
2. 註釋的存在就是爲了幫助理解，而不是混淆本意
3. 註釋的作用是解釋未能自行解釋的代碼，如果註釋本身還需要解釋，就很無語了

4.4.17 函數頭

1. 短函數不需要太多描述
2. 爲只做一件事的短函數選一個好名字，要比寫函數註釋好的多

4.4.18 非公共代碼的 Javadoc

1. 雖然 Javadoc 對於公共 API 非常有用，但對於不打算作公共用途的代碼就令人厭惡了

4.4.19 範例

1. 列舉了作者自己的一段代碼優化效果