[[385297]]

本文轉載自微信公眾號「架構精進之路」，作者架構精進之路。轉載本文請聯系架構精進之路公眾號。

在一次研發(fā)溝通會上，大家關于是否需要代碼注釋做了一番爭執(zhí)(討論)。

主要內容簡述如下：

A：我提議項目應該有個注釋，我們有些程序員幾乎從不注釋代碼，誰都知道沒注釋的代碼是沒法閱讀的。

B：我覺得注釋沒必要，注釋被當做萬靈藥，可是任何實際編碼過的人都知道，注釋反而會使代碼更難讀懂。注釋很容易產生大量的廢話，而編碼語言相對簡明扼要得多。

C：是這么回事。假如代碼不清晰，又怎能注釋的清楚呢?再說，代碼一變，注釋就過時。要是誤讀了過時的注釋，可能又會踩坑了。

C 接著說：另外，注釋過多的代碼更難讀懂，這樣增大了閱讀量。已經有一堆代碼要去讀了，何必再去讀一大堆注釋呢?

A：編輯器要知道的東西全在代碼中?二進制文件里面嗎?爭論注釋有無價值干啥呢?

B：我反對注釋主要是覺得浪費資源。

D：也不能這么說，注釋可能會被濫用，但是注釋用得好時卻妙不可言。另外，在我的工作經歷中，有注釋和沒注釋的我都維護過，我個人還是更愿意維護有注釋的代碼。最后補一句：盡管沒必要制定注釋的標準，但是我還是提倡大家注釋好自己的代碼。

........

關于是否加注釋爭執(zhí)討論比較久，最終大家統一了如下決定：

“提倡加注釋，但不能濫用。我們開發(fā)流程中會有Code Review過程，這樣每個人都將了解好的注釋是什么樣的，同時你遇到不好的代碼注釋，也需要告訴他如何改進。”

問題思考

作為研發(fā)同學，對于代碼“注釋”其實并不陌生。它往往作為我們代碼文檔的特殊補充而存在。

其實在代碼文檔中，起主要作用的因素并非注釋，而是好的編程風格。

編程風格包括：良好的程序結構、易于理解的方法、有意義的變量名和子程序名、常量、清晰的布局，以及最低復雜度的控制流及數據結構。

會后我就在反思：那注釋真的是以啰嗦的方式又重復一遍代碼，所以沒有用么?

好注釋可不是重復代碼或者解釋代碼，它會讓作者的意圖更清晰，注釋應該能在更高的意圖上解釋你想干什么。

日常的注釋

一般情況下，注釋寫的糟糕很容易，寫的出色就很難了。注釋不好只會幫倒忙。

我們來看幾個例子：

// write out the sums 1..n for all n from 1 to num 
current = 1； 
previous = 0； 
sum = 1； 
for(int i=0; i<num; i++){ 
  System.out.Println("Sum = " + sum); 
  sum = current + previous; 
  previous = current; 
  current = sum; 
} 

其實這段代碼計算的是斐波那契(Fibonacci)數列的前num個值。如果注釋錯了，盲目相信注釋可能會南轅北轍，但是好的注釋會事半功倍。

// compute the square root of num using the Newton-Raphson approximation 
r = num / 2； 
while(abs(r - (num/r) > TOLERANCE){ 
  r = 0.5 * (r + (num/r)); 
} 
System.out.println("r = " + r); 

上述例子，它用來計算num的平方根，代碼一般，但注釋比較精準。

注釋的目的

寫代碼和注釋的第一目的是幫助人理解代碼，理解作者的意圖。

所以優(yōu)秀的代碼本身就有自說明功能，只有在代碼本身無法清晰地闡述作者的意圖時，才考慮寫注釋。

即是：注釋應該表達我的代碼為什么要這么做，而不是表達我的代碼做了什么。

我們軟件開發(fā)過程中引入了那么多的設計模式、框架、組件，開發(fā)過程制定了那么詳細的設計規(guī)范、編碼規(guī)范、命名規(guī)范、很大一部分原因就是為了提高代碼的可讀性。

編程語言特別是高級編程語言，本身就是人和機器之間溝通的語言，語言本身就要求滿足人的可讀性，需要用符合我們自然語言的表達習慣，不需要額外的注釋。

注釋怎么寫?

當然，好代碼 > 差代碼+好注釋，好的注釋是很有價值的，壞注釋不僅浪費時間還可能有害，自解釋的代碼最好。

當然，好代碼 > 差代碼+好注釋，好的注釋是很有價值的，壞注釋不僅浪費時間還可能有害，自解釋的代碼最好。好的注釋不是重復代碼或解釋它，而是使代碼更清楚，注釋在高于代碼的抽象水平上解釋代碼要做什么事。

具體的操作手段，包括但不限于以下幾點：

• 適當注釋，仔細衡量，不要隱晦也不要多余;
• 注意存在變更情況是，需要及時更新;
• 注釋代碼中一些tricky的技巧或者特殊的業(yè)務邏輯，否則會讓讀代碼的人摸不著頭腦;
• 如果附上jira、bug、需求等的地址能夠幫助理解代碼，可以適當加上;
• 如果代碼命名良好，結構合理，一般來說是不需要什么注釋的。但是用一句話解釋下意圖和功能也是極好的，因為很多時候僅僅是想知道代碼怎么用，讀一句注釋要比分析幾十行代碼快得多。

注釋的原則

1)寫注釋應遵循奧卡姆剃刀原則：如無必要，勿增實體

注釋寫的不好、維護得不好(比如改了代碼沒改注釋)會導致代碼的可讀性變差。

2)有句話叫“代碼即注釋”，雖然不完全是，但有道理的

把代碼寫好、寫漂亮，注釋就可以精煉，也必然能寫得更易懂。此外，把思路(難的、關鍵的)寫清楚，比啥Author、Date重要多了。抓重要信息。

3)建議注釋里盡量寫為什么，而不是做了什么

做了什么，看代碼就好，代碼不會騙人。但為什么要寫成這樣，有時候就非常讓人困惑。有可能是處理某個corner case，有可能是繞過某個系統限制，也可能是什么奇葩需求，這種代碼，沒有當時的 context，過幾個月看，像甲骨文一樣，不知道是想干什么。再有看不順眼來優(yōu)化一下，以后就不知道哪個地方會崩了。

其實，大部分的代碼應當是不言自明的，不需要注釋的。

總結

• 好的注釋才有價值

該不該注釋是個需要認真對待的問題。差勁的注釋只會浪費時間。好的注釋才有價值。注釋的位置可以在：變量特定的含義和限制、某個職責代碼塊的開始、一般控制結構的開始、子程序調用處、方法開始處描述功能、類開始處描述功能。

• 源代碼應當含有程序大部分的關鍵信息。

只要程序依然在用，源代碼比其他資料都能保持更新，故而將重要信息融入代碼是很有好處的。

• 好代碼本身就是最好的說明

如果代碼太糟，需要大量注釋，應先試著改進代碼，直至無須過多注釋為止。

• 注釋應說出代碼無法說出的東西

例如概述或用意等信息。注釋本身應該包含的是對代碼的簡潔的抽象概括，而不是具體代碼的實現細節(jié)。

• 注釋風格也應該簡潔易于維護

有的注釋風格需要許多重復性勞動，應舍棄之，改用易于維護的注釋風格。

作者：架構精進之路，專注軟件架構研究，技術學習與個人成長。