每隔一段時間，網(wǎng)上總會突然出現(xiàn)一些令人討厭的帖子，其觀點是：不應(yīng)該為代碼寫注釋，它存在的唯一原因是因為代碼本身不足夠好。對于這些論點，我完全不能茍同。

爛代碼

他們的觀點也不完全是錯誤的。沒有人能說自己的代碼足夠好。代碼本身也會慢慢變壞。你知道什么時候代碼腐爛得最厲害嗎？當(dāng)你六個月沒有碰這些代碼的時候！

當(dāng)回過頭再讀的時候，你會非常好奇：“這個作者到底是怎么想的？”（于是，使用 Git blame 來查看歷史記錄，沒想到代碼竟然是自己寫的，因為這是你的代碼。）

反對注釋者的論點是：需要注釋的唯一原因是你的代碼不夠“清晰”。如果代碼重構(gòu)、命名和組織地更好，那就不需要這些注釋了。

今天，當(dāng)整個項目和問題空間都裝在你的腦袋里的時候，你自然會覺得代碼是干凈、清晰和優(yōu)雅的。但是，當(dāng)六個月后，又或是 CTO 剛好在生產(chǎn)系統(tǒng)上突然發(fā)現(xiàn)一個非常嚴重的 bug，在主管緊盯的情況下，某個可憐的家伙不得不去調(diào)試你的代碼的時候，這些代碼可能對你已經(jīng)有些模糊了。

你無比熟悉的一段代碼，嘗試去理解其他人在什么場景下不能理解，這是一種非常難以掌握的技能。不過，它具有無可估量的價值，幾乎和一次就能把代碼寫到位的能力一樣重要。在工業(yè)界中，基本上沒有人是獨行俠。即使真地在獨自寫代碼，你也會遺忘代碼這么寫的緣由或者昨天深夜“工程代碼”核心部分的確切目的。未來一旦你離職，接替你的人不得不去理解每一個僅藏在你的腦袋里的小偏好和習(xí)慣。

所以，寫上一個即使在現(xiàn)在看來過于淺顯的注釋也不是一個壞事情。有時候，它甚至?xí)砭薮蟮膸椭?/p>

無注釋經(jīng)常導(dǎo)致代碼更難以理解

某些人聲稱：移除注釋將會使代碼變得更好，因為這迫使你編寫更清晰的代碼。我對此亦不以為然，因為我不認為有人會實際寫上一些次佳的代碼，并且寫上一些注釋來解釋這種行為（除了// TODO: 這是一個臨時的解決方法，我會稍后修正之外）。我們都會寫出在各種外部條件（通常是時間）下自認為最好的代碼。

為去除注釋而重構(gòu)代碼的問題在于，這種努力往往事與愿違，會產(chǎn)出更壞的代碼。典型例子是重構(gòu)一行復(fù)雜的代碼，將之提取到一個獨立的函數(shù)中，并取一個望文生義的名字。這個行為看上去很棒，但是，現(xiàn)在你為閱讀代碼的人帶來了一個上下文切換點。替代真實代碼的是一個函數(shù)調(diào)用，于是，他們不得不滾動到函數(shù)定義的地方，記住和對照函數(shù)聲明和調(diào)用的參數(shù)，并且將函數(shù)返回值代入到調(diào)用的地方。

另外，清晰的函數(shù)名僅僅能夠提供非常短小的注釋。任何需要多余一小段短語的注釋無法（或者不應(yīng)該）概括到一個函數(shù)名中。因此，你最終會得到一個其上有注釋的函數(shù)。

的確，一個非常短小的函數(shù)都可能導(dǎo)致困惑和更復(fù)雜的代碼。如果看到這樣的函數(shù)，我會去搜索這個函數(shù)在哪些地方被調(diào)用。如果只有一個地方，我就會去思考，這是一個確實封裝了全局邏輯的通用代碼塊呢（譬如 NameToUserID），還是，這個函數(shù)嚴重依賴調(diào)用端的特定狀態(tài)和實現(xiàn)，并且不能在其他地方正確工作。隨著把這些代碼提取一個函數(shù)里面，你本質(zhì)上在其余的代碼庫中暴露了這些實現(xiàn)細節(jié)，這么草率的做決定是不合適的。即使你知道這個函數(shù)其他人不應(yīng)該調(diào)用，其他人還會在某些地方調(diào)用它，即便這些地方不合適這么做。

小函數(shù)的相關(guān)問題在 Cindy Sridharan 在 medium 網(wǎng)站上的帖子[1]中有更加詳細的闡述。

我們甚至可以深入討論長短變量名的比較和權(quán)衡，但是就此打住吧，一般你不可能接受更長的變量名了。除非你的變量名就是你想寫的完整的注釋，否則你還是會丟失信息而不得不添加到注釋中。我認為我們可以達成一致：usernameStrippedOfSpacesWithDotCSVExtension 是一個可怕的變量名稱。

我不是說我們不應(yīng)該提煉代碼，讓它們更加清晰和優(yōu)雅。絕對要這么做！這是一個杰出開發(fā)人員的特征。但是，代碼清晰性和有注釋是正交的，撰寫良好的注釋也是杰出開發(fā)人員的特征。

沒有壞注釋

在這些討論中給出的壞注釋的例子都是些小錯誤，除了那些啟蒙編程課程外，在實際工作中幾乎不會碰到。

// 實例化一個錯誤對象
var err error

不錯，這個注釋很清楚，但不是非常有用。不過同時，它實際上也沒有什么壞處。

在瀏覽代碼時，雖然有些不待見，但也很容易被忽略。如果開發(fā)者能夠在其中包含一個有用的注釋，能夠節(jié)省我數(shù)小時鍵盤工作時間的話，我寧愿看成百這樣的簡單注釋，而不是沒注釋。

我非常確信，不會有任何代碼會說“伙計，這段代碼非常容易理解，所以不需要提供任何注釋?！?實際情況恰恰完全相反。

實際上，我找到了一些嚴重缺失注釋的代碼 - Go 標(biāo)準庫。它的代碼非常精良，但在很多情況下，如果在讀取代碼前對其功能沒有深刻理解，那么理解他們?yōu)槭裁催@么設(shè)計將是個挑戰(zhàn)。如果能加一些注釋，用于解釋代碼的邏輯和設(shè)計意圖，將使 Go 標(biāo)準庫更加容易閱讀。在這篇文章中，我主要討論實現(xiàn)代碼里的注釋，而不是通常的公開函數(shù)的文檔注釋（通常情況下，它們也是非常棒的）。

任何注釋勝過無注釋

另外一個反注釋者喜歡拿出來的例子，可以用下面的簡潔有力的圖片來展示（證明其論點）:

哈，極好笑的，有人更換了瓶子里面的東西但是沒有更新外面的標(biāo)簽。

但是，這是 20 年前的問題了，當(dāng)時通常不進行代碼審查。不過，現(xiàn)在代碼審查已經(jīng)非常普遍了。如果檢查注釋和實現(xiàn)是否匹配不是你們代碼審核流程的一部分，那么最好檢查一下你們的代碼審核流程。

這不是說不會犯錯誤，實際上我昨天剛提交了一個“注釋和實現(xiàn)不一致”的 bug。類似“無注釋比錯誤注釋好”的言論初聽起來是正確的，然而，當(dāng)你認識到如果沒有注釋，開發(fā)人員猜錯代碼的功能比錯誤注釋的出現(xiàn)的概率高的多的時候，你會改變你的看法。

即使這種情況真的發(fā)生，代碼被修改了，你依然可以獲取有價值的信息：代碼以前的用途。修改僅僅和原先有些許不同罷了，它依舊完成基本相同的功能。為了版本控制和向后兼容，同一個函數(shù)在不改變名稱和簽名的情況下，在功能上發(fā)生劇烈變化的頻率有多少？基本上非常少。

就拿我昨天發(fā)現(xiàn)的 bug 來說，我們調(diào)用 client.SetKeepAlive(60)。而 SetKeepAlive 函數(shù)的注釋是 “SetKeepAlive 在發(fā)送 PING 請求之前，客戶端需要等待指定數(shù)量的時間（以秒為單位）”?？瓷先ズ馨?，不是嗎？知道我注意到 SetKeepAlive 的參數(shù)是 time.Duration。

如果沒有其他指定的單位，60 這個整數(shù)將使用 Go 的 duration 的缺省單位納秒。哎，某人更新了該函數(shù)，使用 Duration 類型來替換 Int。有趣的是，它仍然向下取整到了最接近的秒數(shù)，所以注釋不是不正確，只是有些誤導(dǎo)罷了。

為什么？

最重要的注釋是為什么要注釋。為什么代碼是按照設(shè)計來執(zhí)行的？為什么這個 ID 需要小于 24 個字符？為什么要在 Linux 下面隱藏這個選項？諸如此類。這些問題為什么重要的原因是你無法從代碼中提煉出來。這些注釋總結(jié)了開發(fā)者獲得的經(jīng)驗教訓(xùn)，商業(yè)或系統(tǒng)層面的限制條件等，它們是價值無量的，并且?guī)缀鯚o法從其他途徑獲得（例如，函數(shù)取名應(yīng)該反映函數(shù)做什么而不是為什么）。

那些用于說明代碼功能的注釋往往不是特別有用的，因為如果擁有足夠的時間和努力，你總能夠理解代碼的功能。本質(zhì)上，通過函數(shù)定義，代碼往往會告訴你它的具體功能，但這不意味著你不應(yīng)該寫任何注釋。確實應(yīng)該力爭寫出最清晰簡潔的代碼，但是注釋不需要任何額外的運行時開銷，如果你覺得有人會錯誤理解一些代碼或者理解上有困難，應(yīng)該寫上一些注釋。至少，這個會節(jié)省他們半個小時來理解你的代碼，這些注釋也會在很大程度上幫助他們避免錯誤地修改或使用你的代碼，從而導(dǎo)致 bug 的產(chǎn)生。

測試

一些人認為函數(shù)的功能測試案例就相當(dāng)于文檔。某種程度上說，確實是這樣的。但是，在我的效率文檔表中，它的優(yōu)先級非常低。為什么呢？因為它們極其精確而且瑣碎，僅僅覆蓋了功能的很少一部分。每一個測試僅確切地測試一個特定的輸入和與之相配的輸出。任何超過一個簡單函數(shù)的情況，你很可能需要一大串代碼來構(gòu)建輸入和輸出。

對于大多數(shù)編碼而言，描述一個函數(shù)的主要功能比寫代碼去完整測試要容易的多。

很多時候我的測試代碼行數(shù)倍于函數(shù)實現(xiàn)本身，然而文檔注釋僅僅需要寥寥幾行而已。

此外，測試僅僅解釋了函數(shù)的功能。函數(shù)的設(shè)計功能是什么？它們不能解釋為什么，但是就像前面提到的，設(shè)計目的和意圖總是更重要的。

你確實應(yīng)當(dāng)測試你的代碼，通過一些邊界測試案例，測試對于判定代碼在邊界條件下是否能夠正常工作非常有用。但是一般而言，如果到了必須通過閱讀測試案例來理解代碼的地步的話，那么已經(jīng)是一個危險信號，告訴我們需要去編寫更多更好的注釋了。

結(jié)論

除了一些非常簡單的例子以外, 有用注釋和無用注釋的邊界是非常難于去發(fā)現(xiàn)的。

所以，我寧愿人們站在多寫注釋的一方。你無法知道下一個可能閱讀你代碼的人是誰，所以能幫助他們的是盡你所能寫上一大堆的注釋。盡量寫到你認為太多了，然后再多寫一些，這個數(shù)量估計就正好了。