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