[[430029]]

今天和大家聊聊代碼注釋：

• 為什么很多人不喜歡寫注釋?
• 要不要寫注釋?
• 該怎么寫注釋?

現在的項目開發里，代碼注釋就像程序員的頭發，越來越少。

尤其是國內，這種現象不僅是在小公司小團隊中司空見慣，就算在大公司，以及大團隊中的開源項目里，也是屢見不鮮。

上圖是我在阿里的 Druid 項目源碼里截的。DruidDataSource 是 Druid 重度使用的核心類，非常關鍵，可是哪怕這種關鍵的核心類，也見不到什么注釋。

這張圖則來自阿里的另一個著名開源項目Dubbo。DubboProtocol 是 dubbo 協議的實現類，而 dubbo 協議是 Dubbo 項目中最常見，使用最頻繁的默認協議，一樣沒什么注釋。

沒有注釋對我們讀代碼帶來了很多的不便之處。就像扔給你一個數碼產品，上面堆疊著密密麻麻的功能按鍵，但是卻沒有給你說明書。

那為什么代碼注釋消失了呢?

我嘗試總結一下原因：

1. 國內程序員的職業環境對加注釋不友好

在國內這種環境里，程序員們每天在苦悶的 996 中掙扎，各種大活小活不斷地做著，正常寫代碼都忙得不可開交，加注釋更是進一步提升了工作量，沒人喜歡自己給自己加工作量的。

咱們想想，在費勁巴拉地寫完一大堆代碼之后，經過反復自測修改之后，好不容易調通了，腦子已經暈乎乎的了，你此時會有多大心思去寫這段注釋呢?

又再想想，你可能想著要給代碼加注釋呢，突然這邊產品拉你開會，又或者那邊運營告訴你，需求變了，剛寫好的代碼還得再改改……此時，你還有給代碼加注釋的念頭嗎?

另外，注釋這事兒，寫好了是很費精力的。一般來說，一段好的注釋，要能在有限的行數之內說明出：被它注釋的代碼到底做了什么，是個怎樣的概念以及為什么會寫這段代碼。

寫注釋麻煩不說，關鍵是注釋還不算咱們程序員的工作量。

程序員的工作是把業務用程序實現，工作結果里不看你注釋了多少代碼，也不看你注釋寫的好還是壞，只看你的程序是不是寫完了，滿足了需求沒有，會不會上線出什么問題。

至于注釋，它滾出了程序員兄弟們的 KPI。有多少公司能像 Google 那樣去 Review 代碼的?BAT 有一個算一個，都差點意思。

所以，國內程序員們糟糕的環境，是代碼注釋少的首要原因。

2. 看待注釋的方式出現了變化

Java 是一門面向對象的語言，從它出世以來，業界就不斷地為 Java 制定了數不清的規范。

在 2008 年，集這些規范于大成的《Clean Code》—— 中文名叫《代碼整潔之道》這本書出現了。

在《代碼整潔之道》中有個理念就是，注釋是為了彌補代碼表達能力不足的一種不得已的做法。如果代碼能表達清楚，那就沒必要寫注釋。

甚至，這本書的作者認為寫注釋都需要用 failure 這個詞來形容，也就是說，如果你寫了注釋，那就說明你的代碼不夠好，你寫好代碼的努力失敗了。

這個理念在業界也被不少大牛們認可了。所以，后面就有越來越多的人認為：代碼寫的夠好，就不用寫注釋了。

如果大家有空，可以去看看《代碼整潔之道》的第四章，里面詳細說明了這種如今被業界不少人接受的關于注釋的理念。

所以，“好代碼不需要注釋”這種觀點也是造成注釋少的一個原因。

3. 注釋沒有規范，導致質量參差不齊

很多團隊里，是沒有注釋規范的。對怎么注釋，在哪里注釋沒有任何規定，隨意程序員們自由發揮。

這就麻煩了，注釋一旦寫了，它就很關鍵了。因為

錯誤的注釋，比沒寫注釋還禍害人。

注釋寫的很差，那不僅沒起到注釋本應該起到幫助讀代碼的作用，反而還可能影響讀代碼，甚至還能把人帶坑里。

如果沒有注釋規范，往往經常就會出現有人做的好有人做的差的情況。

比如，有人到處加注釋，i = i + 1; //把i加1連這種簡單代碼都恨不得加注釋，這就有點脫褲子放屁了。

還有的人寫注釋了，但是需求變了，代碼改了之后，注釋懶得改了。又或者是改代碼的人不是原作者，新人改完之后壓根就沒意識到要改注釋。

所以，如果沒有規范，很多程序員對注釋沒有什么正確的概念，沒寫好注釋由此還引來了埋怨……久而久之，就沒人愛干加注釋這件事了。

到底應該怎么寫注釋呢?

談了那么多不寫注釋的原因，這里也想說明一下我對注釋的觀點。

我個人并不怎么贊同《代碼整潔之道》對注釋的觀點，我自己讀有好注釋的代碼，直接就省了五成以上的力氣。有好注釋的代碼讀起來，就像常年腦血栓，一朝被皮搋子打通了一樣，那叫一個順暢。

比如，看看 Netty 的注釋：

/** 
 * A nexus to a network socket or a component which is capable of I/O 
 * operations such as read, write, connect, and bind. 
 * <p> 
 * A channel provides a user: 
 * <ul> 
 * <li>the current state of the channel (e.g. is it open? is it connected?),</li> 
 * <li>the {@linkplain ChannelConfig configuration parameters} of the channel (e.g. receive buffer size),</li> 
 * <li>the I/O operations that the channel supports (e.g. read, write, connect, and bind), and</li> 
 * <li>the {@link ChannelPipeline} which handles all I/O events and requests 
 *     associated with the channel.</li> 
 * </ul> 
 * 
 * <h3>All I/O operations are asynchronous.</h3> 
 * <p> 
 * All I/O operations in Netty are asynchronous.  It means any I/O calls will 
 * return immediately with no guarantee that the requested I/O operation has 
 * been completed at the end of the call.  Instead, you will be returned with 
 * a {@link ChannelFuture} instance which will notify you when the requested I/O 
 * operation has succeeded, failed, or canceled. 
 * 
 * <h3>Channels are hierarchical</h3> 
 * <p> 
 * A {@link Channel} can have a {@linkplain #parent() parent} depending on 
 * how it was created.  For instance, a {@link SocketChannel}, that was accepted 
 * by {@link ServerSocketChannel}, will return the {@link ServerSocketChannel} 
 * as its parent on {@link #parent()}. 
 * <p> 
 * The semantics of the hierarchical structure depends on the transport 
 * implementation where the {@link Channel} belongs to.  For example, you could 
 * write a new {@link Channel} implementation that creates the sub-channels that 
 * share one socket connection, as <a href="http://beepcore.org/">BEEP</a> and 
 * <a href="http://en.wikipedia.org/wiki/Secure_Shell">SSH</a> do. 
 * 
 * <h3>Downcast to access transport-specific operations</h3> 
 * <p> 
 * Some transports exposes additional operations that is specific to the 
 * transport.  Down-cast the {@link Channel} to sub-type to invoke such 
 * operations.  For example, with the old I/O datagram transport, multicast 
 * join / leave operations are provided by {@link DatagramChannel}. 
 * 
 * <h3>Release resources</h3> 
 * <p> 
 * It is important to call {@link #close()} or {@link #close(ChannelPromise)} to release all 
 * resources once you are done with the {@link Channel}. This ensures all resources are 
 * released in a proper way, i.e. filehandles. 
 */ 
public interface Channel extends AttributeMap, Comparable<Channel> { 

Channel 是 Netty 里非常核心的一個接口，你直接看注釋，一下子就能理解了 Netty 為啥搞出個 Channel 類來，Channel 類你可以怎么玩兒，這些 Netty 在注釋給你說得清清楚楚、明明白白。

所以，我覺得注釋一定是要的，只是需要有個標準，也要有個度。

從實踐上看，我們團隊有這么幾個必須加注釋的標準：

1. 復雜的業務邏輯

業務邏輯關聯太多的東西又或者步驟非常多，更或者兩者兼有，那么就很少有人會去耐心仔細的去一行一行的把整個代碼全部讀通理順。

這時候，必須在業務邏輯實現的相關類中，把類在業務邏輯實現中是個什么成分，為什么這么設計類，以及對應的業務邏輯都要講清楚。并且重構代碼后，注釋也必須跟著重構。

2. 晦澀的算法

算法也要加上注釋的，尤其那些深奧的算法。大家不可能都是算法專家，能一下子就通過代碼理解到算法實現的真諦。所以，這里也要加上注釋，一般是說明這是用了個什么算法，這套算法的出處或者附上相關文章的引用地址。

3. 非常規的寫法

非常規的寫法往往是有特殊情況，不得已為之的。比如，為了得到更好的性能;又比如，為了修復一個 bug，卻不想對代碼進行大改動。

總之，非常規的寫法就是反模式、反套路的，有時候甚至會違反程序員的直覺。像這些做法，必須在注釋中寫明這樣實現的原因。

4. 可能有坑卻暫時沒太好解決辦法

有些時候，需求出的夠難夠復雜，時間上催的又很急，你根本沒辦法馬上想到特別好的辦法去實現。只能臨時想個簡單粗暴的方案，先湊活著。甚至還會在某些地方，把一些變量的值寫死先去把本期的需求實現了。

像這種就很可能就會給后面挖坑了。這時候，注釋必須加上為什么要這么解決的原因，還必須加上 //TODO 這類的，表示后面需要進行進一步的修改。

5. 關于項目核心的接口、類和字段

做項目的時候，需求中的很多核心概念很可能會被映射到對應的接口或者實體類上，如果在這些核心接口和實體類加上清楚的注釋，寫明對應的業務概念，那么，后面再維護項目的時候，真的是事半功倍。

比如，我們在一套批量調度系統里，可能有多種任務的概念，有需要限定執行時間的任務，也有不需要限定執行時間的任務，那么實現上，就可能有個 LimitedTimeTask 類對應限定時間的任務，還有個 UnLimitedTimeTask 類去對應不需要限定執行時間的任務。那這兩個類就必須加上注解，寫清楚對應的業務概念。

如果特定概念是復合的，是由多個小概念構成，卻必須用一個接口或者一個類來表示，那很可能實現上，就還得用字段去映射這些小概念，那么這些字段也得加上注釋說明起對應的概念。

總之，注釋我個人理解必須要有，但是不可能太泛濫，必須有節制、有規范的加。

最后，咱們說白了，我對注釋的態度就是，和寫代碼一樣，要有規范。

在這里和管理者說一句，如果你希望大家寫好注釋，不能就靠一句“必須寫注釋”這么高高在上的話去要求大家。沒有規范，你就不能完全怪程序員不加注釋了。

最最后，大劉提醒我“四哥，注釋規范里還要再加一條”

本文轉載自微信公眾號「四猿外」，可以通過以下二維碼關注。轉載本文請聯系四猿外公眾號。