一場關於程式碼註釋的爭執，引發的三點思考

在一次研發溝通會上，大家關於是否需要程式碼註釋做了一番爭執（討論）。

主要內容簡述如下：

A：我提議專案應該有個註釋，我們有些程式設計師幾乎從不註釋程式碼，誰都知道沒註釋的程式碼是沒法閱讀的。

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

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

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

A：編輯器要知道的東西全在程式碼中？二進位制檔案裡面嗎？爭論註釋有無價值幹啥呢？

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

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

……。。

關於是否加註釋爭執討論比較久，最終大家統一瞭如下決定：

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

問題思考

作為研發同學，對於程式碼“註釋”其實並不陌生。它往往作為我們程式碼文件的特殊補充而存在。

其實在程式碼文件中，起主要作用的因素並非註釋，而是好的程式設計風格。

程式設計風格包括：良好的程式結構、易於理解的方法、有意義的變數名和子程式名、常量、清晰的佈局，以及最低複雜度的控制流及資料結構。

會後我就在反思：那註釋真的是以囉嗦的方式又重複一遍程式碼，所以沒有用麼？

好註釋可不是重複程式碼或者解釋程式碼，它會讓作者的意圖更清晰，註釋應該能在更高的意圖上解釋你想幹什麼。

日常的註釋

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

我們來看幾個例子：

// write out the sums 1。。n for all n from 1 to numcurrent = 1；previous = 0；sum = 1；for（int i=0； i

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

// compute the square root of num using the Newton-Raphson approximationr = num / 2；while（abs（r - （num/r） > TOLERANCE）{ r = 0。5 * （r + （num/r））；}System。out。println（“r = ” + r）；

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

註釋的目的

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

所以優秀的程式碼本身就有說明功能，只有在程式碼本身無法清晰地闡述作者的意圖時，才考慮寫註釋。

即是：

註釋應該表達我的程式碼為什麼要這麼做，而不是表達我的程式碼做了什麼。

我們軟體開發過程中引入了那麼多的設計模式、框架、元件，開發過程制定了那麼詳細的設計規範、編碼規範、命名規範、很大一部分原因就是為了提高程式碼的可讀性。

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

註釋怎麼寫？

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

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

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

適當註釋，仔細衡量，不要隱晦也不要多餘；

注意存在的變更情況時，需要及時更新；

註釋程式碼中一些 tricky 的技巧或者特殊的業務邏輯，否則會讓讀程式碼的人摸不著頭腦；

如果附上 jira、bug、需求等的地址能夠幫助理解程式碼，可以適當加上；

如果程式碼命名良好，結構合理，一般來說是不需要什麼註釋的。但是用一句話解釋下意圖和功能也是極好的，因為很多時候僅僅是想知道程式碼怎麼用，讀一句註釋要比分析幾十行程式碼快得多。

註釋的原則

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

註釋寫得不好、維護得不好（比如改了程式碼沒改註釋）會導致程式碼的可讀性變差。

2）有句話叫“程式碼即註釋”，雖然不完全是，但是有道理的

把程式碼寫好、寫漂亮，註釋就可以進行精煉，也必然能寫得更易懂。此外，把思路（難的、關鍵的）寫清楚，比如啥 Author、Date 重要多了。抓重要資訊。

3）建議註釋裡儘量寫為什麼，而不是做了什麼

做了什麼，看程式碼就好，程式碼不會騙人。但為什麼要寫成這樣，有時候就非常讓人困惑。有可能是處理某個事情 corner case，有可能是繞過某個系統限制，也可能是什麼奇葩需求，這種程式碼，沒有當時的 context，過幾個月看，像甲骨文一樣，不知道是想幹什麼。再有看不順眼來最佳化一下，以後就不知道哪個地方會崩了。

其實，大部分的程式碼應當是不言自明的，不需要註釋的。

總結

好的註釋才有價值

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

原始碼應當含有程式大部分的關鍵資訊。

只要程式依然在用，原始碼比其他資料都能保持更新，故而將重要資訊融入程式碼是很有好處的。

好的程式碼本身就是最好的說明

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

註釋應說出程式碼無法說出的東西

例如概述或用意等資訊。註釋本身應該包含的是對程式碼的簡潔的抽象概括，而不是具體程式碼的實現細節。

註釋風格也應該簡潔易於維護

有的註釋風格需要許多重複性勞動，應捨棄之，改用易於維護的註釋風格。