[[430029]]

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

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

現(xiàn)在的項目開發(fā)里，代碼注釋就像程序員的頭發(fā)，越來越少。

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

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

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

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

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

我嘗試總結(jié)一下原因：

1. 國內(nèi)程序員的職業(yè)環(huán)境對加注釋不友好

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

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

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

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

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

程序員的工作是把業(yè)務(wù)用程序?qū)崿F(xiàn)，工作結(jié)果里不看你注釋了多少代碼，也不看你注釋寫的好還是壞，只看你的程序是不是寫完了，滿足了需求沒有，會不會上線出什么問題。

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

所以，國內(nèi)程序員們糟糕的環(huán)境，是代碼注釋少的首要原因。

2. 看待注釋的方式出現(xiàn)了變化

Java 是一門面向?qū)ο蟮恼Z言，從它出世以來，業(yè)界就不斷地為 Java 制定了數(shù)不清的規(guī)范。

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

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

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

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

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

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

3. 注釋沒有規(guī)范，導(dǎo)致質(zhì)量參差不齊

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

這就麻煩了，注釋一旦寫了，它就很關(guān)鍵了。因為

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

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

如果沒有注釋規(guī)范，往往經(jīng)常就會出現(xiàn)有人做的好有人做的差的情況。

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

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

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

到底應(yīng)該怎么寫注釋呢?

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

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

比如，看看 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 在注釋給你說得清清楚楚、明明白白。

所以，我覺得注釋一定是要的，只是需要有個標(biāo)準(zhǔn)，也要有個度。

從實踐上看，我們團隊有這么幾個必須加注釋的標(biāo)準(zhǔn)：

1. 復(fù)雜的業(yè)務(wù)邏輯

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

這時候，必須在業(yè)務(wù)邏輯實現(xiàn)的相關(guān)類中，把類在業(yè)務(wù)邏輯實現(xiàn)中是個什么成分，為什么這么設(shè)計類，以及對應(yīng)的業(yè)務(wù)邏輯都要講清楚。并且重構(gòu)代碼后，注釋也必須跟著重構(gòu)。

2. 晦澀的算法

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

3. 非常規(guī)的寫法

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

總之，非常規(guī)的寫法就是反模式、反套路的，有時候甚至?xí)`反程序員的直覺。像這些做法，必須在注釋中寫明這樣實現(xiàn)的原因。

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

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

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

5. 關(guān)于項目核心的接口、類和字段

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

比如，我們在一套批量調(diào)度系統(tǒng)里，可能有多種任務(wù)的概念，有需要限定執(zhí)行時間的任務(wù)，也有不需要限定執(zhí)行時間的任務(wù)，那么實現(xiàn)上，就可能有個 LimitedTimeTask 類對應(yīng)限定時間的任務(wù)，還有個 UnLimitedTimeTask 類去對應(yīng)不需要限定執(zhí)行時間的任務(wù)。那這兩個類就必須加上注解，寫清楚對應(yīng)的業(yè)務(wù)概念。

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

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

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

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

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

本文轉(zhuǎn)載自微信公眾號「四猿外」，可以通過以下二維碼關(guān)注。轉(zhuǎn)載本文請聯(lián)系四猿外公眾號。