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

爛代碼

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

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

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

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

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

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

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

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

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

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

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

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

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

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

沒有壞注釋

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

// 實(shí)例化一個(gè)錯(cuò)誤對(duì)象
var err error

不錯(cuò)，這個(gè)注釋很清楚，但不是非常有用。不過同時(shí)，它實(shí)際上也沒有什么壞處。

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

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

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

任何注釋勝過無注釋

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

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

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

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

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

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

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

為什么？

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

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

測(cè)試

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

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

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

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

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

結(jié)論

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

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