前言
代碼是否應(yīng)該寫注釋，目前大概有兩種看法。第一種認為，優(yōu)秀的代碼不需要注釋，即很多人推崇的代碼即注釋；第二種認為，寫代碼應(yīng)該要寫注釋。
在此，先給出結(jié)論：代碼需要注釋。但是不是每行都需要注釋，或者需要多少注釋，我們會在接下來的文章中討論這個問題。（文中的例子均為PHP代碼）
首先，我們先討論下代碼即注釋 的問題。
我們先思考下，代碼即注釋的觀點是否正確。對于代碼即注釋，主要有兩個好處。 其一是在不寫注釋的情況下，避免了一定的工作量，這個工作量包含注釋的編寫，維護以及注釋規(guī)范的保持。在實際工作中，我們都遇到過注釋和實際代碼意圖不一致的情況，這就是注釋沒有維護好，為代碼的維護造成更多的負擔(dān)。 比如下面這個經(jīng)常被用來被調(diào)侃的例子
<?php/** 獲取明天這個時候的時間戳./*/* @return int 時間戳.*/function getTomorrowTime(){ sleep(86400); return time();}復(fù)制代碼
其二是代碼即注釋，能提高團隊的代碼命名、可讀性等。對于一個有強制代碼風(fēng)格檢查、Code Review執(zhí)行到位的團隊來講，推崇代碼即注釋，確實會強有力地推動代碼的命名和可讀性，提升編碼能力。
從以上兩點來講，代碼即注釋的觀念是正確的，也確實能給團隊帶來收獲。但是，在團隊實踐代碼即注釋，也是有前置條件的。
首先，團隊必須是相對固定的，這里的相對固定是指團隊成員不會經(jīng)常性流動。一個團隊要達到代碼即注釋的水平，是很難的，即使你的團隊是精英團隊，每個人能力極強，但是大概率會有不同的技術(shù)背景，在認知上難免出現(xiàn)差異，這里舉幾個例子：
0) { return 100 / $a; } return 0;}// vs function test() { return $a > 0 ? 100 / $a : 0;}
我們先不論誰好誰壞，這種不一致性是確實存在的。 要到達代碼即注釋，最重要的一點是你需要將團隊成員的編碼認知，基本拉到同一個水平，并且團隊內(nèi)部形成大家都認可的最佳實踐。要做到這一點，需要團隊長時間的協(xié)作和磨合。 對于一個流動性大的團隊，是無法做到這一點的，假設(shè)團隊5個人，剛把大家的認知統(tǒng)一，結(jié)果走了3個人；補充的3個新人，還得重新去拉齊大家認知，人員再流動，再拉齊，永遠達不到目標(biāo)。所以對于流動性極高的團隊，老老實實寫注釋是最好的選擇。
其次，你得有拉齊團隊認知的工具和文化。比如嚴格的Code Review，自動化的代碼風(fēng)格檢查等。一個Code Review 都做不好的團隊，代碼風(fēng)格、邏輯實現(xiàn)千奇百怪，怎么能統(tǒng)一認知，怎么做到代碼即注釋呢。
總結(jié)一下，要在團隊中實踐代碼即注釋，首先得考慮團隊的流動性、其次有沒有相關(guān)工具和規(guī)范；對于一個新團隊，即使有條件，也要長期堅持不懈推行規(guī)范，建立文化，才能得以成功。
最后，在談?wù)劥a即注釋還有一個弊端，在一些特定的場景下，代碼中會包含一些隱藏的邏輯，無法很好通過代碼表達出來。對于不了解隱藏邏輯的人來說，往往會錯誤地使用該代碼，造成Bug。
鑒于以上的原因，加上國內(nèi)這種為搶占市場快速產(chǎn)出而導(dǎo)致遍地加班的環(huán)境，代碼注釋絕對是有必要的，至少使用90%以上的團隊。
代碼注釋寫多少合適
對于這個問題，我們傾向于從三個情況考慮： 第一，你的團隊是踐行代碼即注釋的團隊，并且做得還不錯；對于這種情況，常規(guī)的代碼注釋可以省略，但是對于業(yè)務(wù)邏輯復(fù)雜或者包含隱藏邏輯的代碼，這是需要注釋的。
第二，你的團隊有明確的注釋規(guī)范；這種情況按團隊規(guī)范來即可。
第三，你的團隊沒有良好代碼的基因，不推崇代碼即注釋，也沒有規(guī)范；這種情況下，團隊負責(zé)人需要評估，是制定一套注釋規(guī)范，還是踐行代碼即注釋。我們的建議一般都是先制定注釋規(guī)范，因為注釋規(guī)范實現(xiàn)相對于代碼即注釋，時間和成本都要小很多；注釋規(guī)范落地后，再考慮代碼即注釋的問題。
最后，不管是寫注釋還是踐行代碼即注釋，Code Review 都是保證代碼質(zhì)量(包括代碼和注釋本身)的重要工具。
