只要一討論到代碼需不需要注釋，就會(huì)有人說：“只要爛代碼還需要注釋，好的代碼都是自解釋的”。

但是，那么多優(yōu)秀的開源項(xiàng)目總是帶有非常詳細(xì)的注釋，難道是爛代碼不成。反正不管好代碼還是爛代碼，就算是沒有注釋的好代碼，讀起來也比有注釋完備的爛代碼難讀、難懂。

再者說，什么是好代碼，這個(gè)標(biāo)準(zhǔn)很難評(píng)。

沒有bug的代碼就是好代碼嗎？性能優(yōu)越的就是好代碼嗎？還是說簡單易懂的就是好代碼呢？

圖片

不知道你有沒有碰到過下面這幾種場景：

（一） 同事問你，或者你問同事：“你這代碼怎么沒注釋？”有多少人會(huì)回答是因?yàn)槲掖a寫的好，不需要注釋的。就算真有人這么說，得到的回復(fù)也是「辣雞，什么都不是」。

（二） 某個(gè)項(xiàng)目或者某塊功能突然要補(bǔ)上設(shè)計(jì)文檔，而功能又不是你做的。你可能會(huì)說：得看看這部分代碼有沒有注釋，沒有注釋的話，可能得多需要一些時(shí)間。然后寫的過程，如果真的沒有注釋，大概率也會(huì)在心里嘀咕『代碼寫這么爛，還不加注釋』

（三） 你接手了一個(gè)新項(xiàng)目，要改一些功能，如果碰巧這些功能有注釋，你會(huì)謝天謝地，然后謝謝當(dāng)初寫代碼加注釋的家伙。

無論是我們看自己之前的代碼，還是接手別人的代碼，有注釋是百利而無一害的。

“Redis 之父” antirez 將注釋分為 9 種類型，其中前6種是提倡的，后三種是最好要避免的。

1、函數(shù)注釋

目的是讓讀者無需先讀代碼，可將某些代碼視為黑盒，通常位于函數(shù)定義頂部或其他功能性代碼塊處，類似內(nèi)聯(lián) API 文檔，可確保文檔與代碼同步更新、提高作者修改文檔的概率、方便讀者查找文檔。

很多時(shí)候我們只是想使用某個(gè)方法，而其內(nèi)部可能很復(fù)雜，比如某個(gè)非常專業(yè)的算法，可能讀半天都看不懂， 這種情況，如果有對(duì)方法的說明，我們只要根據(jù)說明來用就可以了。

一些開放API就類似于這種注釋，我們經(jīng)常抱怨某大廠的開放平臺(tái) API 文檔寫的那叫一個(gè)垃圾，根據(jù)說明文檔來會(huì)踩很多坑。同理，如果一個(gè)復(fù)雜的方法沒有注釋，或者注釋很垃圾，會(huì)給使用者帶來很多麻煩。

2、設(shè)計(jì)注釋

常位于文件開頭，說明代碼使用特定算法等的方式和原因，提供更高層次的概述，有助于讀者理解代碼，且能讓讀者了解設(shè)計(jì)過程，增強(qiáng)對(duì)代碼的信任。

大的開源項(xiàng)目中幾乎每個(gè)文件都有這種注釋，用來解釋這個(gè)文件是干什么用的。

3、Why 注釋

解釋代碼為什么要做某事，即使代碼行為很清晰，這種注釋可能是思考系統(tǒng)改進(jìn)的機(jī)會(huì)。

比如代碼中做了某些特別的操作或動(dòng)作，如果純靠讀代碼，不知道上下文，比如涉及到某個(gè)業(yè)務(wù)，那會(huì)讓使用者一頭霧水，知其然不知其所以然。

4、Teacher 注釋

教學(xué)代碼，對(duì)讀者有很大價(jià)值，能增加可閱讀代碼的程序員數(shù)量。

很多技術(shù)文章或者源碼解讀中都有這樣的注釋，比如寫 HasMap原理的文章，其中涉及到存儲(chǔ)結(jié)構(gòu)、哈希沖突、擴(kuò)容這些原理時(shí)，一定是對(duì)著代碼將會(huì)更清楚，所以多采用在方法中逐行加注釋的方法來說明，讀者一行注釋一行代碼看下來，可以更加輕松的搞清楚內(nèi)在邏輯。

5、Checklist 注釋

由于語言限制等原因，代碼中某些概念或接口無法集中在一處時(shí)，這種注釋會(huì)提醒在修改代碼的某些部分時(shí)要記得修改其他部分，或者警告特定修改的操作方式，在 Linux 內(nèi)核中很常見。

這很像是對(duì)一個(gè)事務(wù)的解釋，一個(gè)事務(wù)會(huì)涉及到多個(gè)階段，但是每個(gè)階段要執(zhí)行的東西可能會(huì)分散到各處，當(dāng)你讀到其中的某個(gè)階段代碼時(shí)，如果有 Checklist 告知你整個(gè)事務(wù)鏈條，那你對(duì)這個(gè)事務(wù)會(huì)理解的更加清晰。

6、Guide 注釋

輔助讀者閱讀代碼，降低認(rèn)知負(fù)擔(dān)，明確劃分代碼、引入即將閱讀的內(nèi)容，雖主觀但對(duì)提高代碼可讀性有幫助，還能使新增代碼更可能插入到合適位置。

這更像是一個(gè)項(xiàng)目的 README 文件，好的開源項(xiàng)目一定有一個(gè)好的 README 文檔，告訴使用者需要什么環(huán)境、要安裝什么依賴包、如何配置參數(shù)、如何啟動(dòng)等等。

7、瑣碎注釋

一些無用且瑣碎的評(píng)論，比如一行非常簡單的代碼，確實(shí)是那種一眼就能看懂的代碼，還非要加上注釋。

比如下面這個(gè)自增語句，非要加個(gè)注釋，莫名其妙的，有這功夫，還是把主要邏輯的注釋寫好吧。

count++;	// 自增

8、債務(wù)注釋

即代碼中的技術(shù)債務(wù)聲明，如 TODO、FIXME 等，雖不太好但有時(shí)可避免遺忘問題，應(yīng)定期檢查并處理。

有時(shí)候?yàn)榱丝焖俚膶?shí)現(xiàn)功能，可能有些邏輯會(huì)有臨時(shí)性的快速方案，然后在對(duì)應(yīng)的位置加上 TODO，之后可能臨時(shí)方案就變成最終方案了。

9、Backup 注釋

開發(fā)者對(duì)舊版本代碼塊或函數(shù)進(jìn)行注釋，因?qū)π麓a不放心，但這是不合適的，源代碼不是用來做備份的。

說實(shí)話，我有時(shí)也會(huì)這么干，寫新方法時(shí)，先把把舊方法注釋掉，萬一有問題的話，直接注釋掉，省的代碼回滾了。

在業(yè)務(wù)頻繁變更的時(shí)候，這種方法確實(shí)也沒什么問題，只要想著在穩(wěn)定之后把注釋的無用方法刪掉就好了。

同樣是接手一份代碼，如果是沒有注釋的，我們?cè)诮邮值臅r(shí)候就難免會(huì)先產(chǎn)生反感、畏難情緒，除非注釋是亂寫的。

我還真見過方法注釋和方法邏輯驢唇不對(duì)馬嘴的，嚴(yán)重懷疑是前輩不想干了，在代碼里下毒。你要是真按照他注釋的來，那就廢了。

最起碼就我而言，我覺得加注釋的代碼比不加注釋的代碼要更友好。加上現(xiàn)在各種AI代碼助手，更應(yīng)該寫注釋了，比如你用 Cursor 寫代碼，你先寫注釋，然后讓 Cursor 給你寫代碼就好了，所以說以后寫注釋可能是一項(xiàng)必備技能，然后是 Review AI 寫的代碼，最后才是寫代碼的能力了。