繼續整理本書的筆記。

第四章 注釋

天真的年代里，我們認為代碼里的注釋就猶如公式旁邊的備注，必不可少，越多與好，越詳細越有用，常常技術頭頭們會把代碼要有詳細注釋放在編碼規范的頭幾條，甚至會有規定所謂的代碼注釋比，即多少行代碼要配上多少行注釋，每次代碼復查時，“注釋不夠啊” “注釋不清晰啊”頭頭A語重心長的對初級碼農說道。現實的年代里，真的是這樣的嗎？一小組的人加班加點，不是在改bug，也不是在加新feature，而是在修補注釋，每個類是做什么的，函數是打哪路醬油的，哪些是來參，哪些是出參，返回值又姓誰名啥。。。不一而舉。年幼的我們還會沾沾自喜，“哈哈，多棒的代碼，因為，滿滿的都是注釋感啊。“ 直到代碼過了幾個迭代之后，我們發現：”WTF！這是誰寫的注釋，函數名字都對不上。“ 然后默默走開，邊想，老子的注釋可不會這樣，邊默默的復制粘貼，熟練的給新加的代碼寫注釋。以前我總以為，代碼的注釋越多越好，越詳細越好，看過本章之后才發現，越詳細的注釋只是掩耳盜鈴而已。本章給出了兩句簡單卻發人深省的總結：

注釋不能美化糟糕的代碼。
代碼才是最好的闡述方式，注釋不是。

很好理解，晦澀混亂的代碼，即便注釋在美妙，也只是隔靴撓癢，改變不了糟糕代碼的事實，相反，簡潔易懂，清晰明了的代碼，配上天時地利的命名，即便沒有注釋，也是瑕不掩瑜。
當然，凡事不可極端，注釋在某些情況下是必不可少的，例如，版權信息這些無法通過代碼展現出來的東西，幾條關于好注釋和壞注釋的參考：

好注釋：

• 法律信息，身為程序員，版權問題沒得商量。
• 對意圖的解釋和闡釋，特別是某些表面看來不尋常甚至看似錯誤的代碼（不過寫這種代碼真的好嗎？）。
• 警示作用的注釋，例如此處代碼至少有8個坑，入坑需謹慎。
• TODO注釋，用以標記由于某種原因，現在沒有實現需要在將來添加的東西，當然務必要確保這些TODO真的To do了，現狀很可能是，幾年后的代碼里幾年前的TODO注釋還在角落里面安靜的做著美男子。如果發現不會取Do了，那就把這條TODO注釋放心刪掉吧，不疼。
• 對外提供的公共接口，這個不多說，多看看各種庫的說明文檔就知道了。
  除了以上幾點，剩下的都是壞注釋了。

壞注釋：

• 自問自答，喃喃自語，注釋完全成了下筆如有神的傀儡，例如：”//如果獲取失敗，那么就重來。“重來what？有多少愛可以重來。。。。
• 多于的注釋，例如（歡樂：)）：

//Guess what? There are two bugs in the following code. Bug bug1 = 0; Bug bugN = 1;

• 誤導性的注釋，這個不多說，誤導人大家都會。
• 循規蹈矩是的注釋，例如函數頭部要寫上固定格式的注釋，不管函數有多么簡單，我想說，注釋都讓你玩出花來了，你咋不上天呢。例如：

/****@param1: input ... ****/ /****@param2: output... ****/ /****@return: .... ****/

• 日志式注釋，起初看到一堆常常的代碼變更日志，覺得格外好，所有變化清清楚楚，但是如果變更記錄需要我們手動維護，我們適用代碼控制系統（SVN， Git）還有意義嗎？
• 廢話連篇，甚至是錯誤的廢話，例如，不僅全是廢話，還有錯誤，連廢話都說說，還能干啥，揍凱~~：

//date Date m_date; //name String m_name; //age unsigned int m_age; //age Address m_address;

• 位置標記，例如新家的代碼段前加上”//Actions///“。
• 括號后面的注釋，例如循環的結束括號，另一個elseif的開始位置，代碼需要加上特定的注釋標識才能清晰，只能說你括號中間的代碼太長了，拆分函數吧，騷年。例如：

for(...) {//begin of for ... ... ...while(...){//begin of while...............}//end of while ... ... ... ... ... }//end of for

• 注釋掉的代碼，這個最煩人，這樣的代碼就像堆積在犄角旮旯的雜物，我們總在想，”或許某一天還能用上吧，暫時先注釋掉，不刪，哈哈“。這種情況應該想收拾房間一樣，果斷”斷舍離“吧，沒用的代碼，堅決刪掉。
• 信息過多，如果有這樣一段注釋：

/* "Long, Long Ago" is a song dealing with nostalgia, written in 1833 by English composer Thomas Haynes Bayly. Originally called "The Long Ago", its name was apparently changed by the editor Rufus Wilmot Griswold when it was first published, posthumously, in a Philadelphia magazine, along with a collection of other songs and poems by Bayly. The song was well received, and became one of the most popular songs in the United States in 1844. In 1939 the tune was given new words (revised slightly in 1941) and a bouncier tempo. It became the 1942 Glenn Miller hit "Don't Sit Under the Apple Tree (With Anyone Else but Me)". In 1950, Patti Page recorded a cover as an alternate flip side to her hit record, "Tennessee Waltz". */ Class LongLongAgo { ... };

總之

注釋只是為代碼服務的東西，切忌喧賓奪主，切記。

總結

以上是生活随笔為你收集整理的[读书笔记] 代码整洁之道（二）的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。