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

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

再者說，什么是好代碼，這個標準很難評。

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

圖片

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

（一） 同事問你，或者你問同事：“你這代碼怎么沒注釋？”有多少人會回答是因為我代碼寫的好，不需要注釋的。就算真有人這么說，得到的回復也是「辣雞，什么都不是」。

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

（三） 你接手了一個新項目，要改一些功能，如果碰巧這些功能有注釋，你會謝天謝地，然后謝謝當初寫代碼加注釋的家伙。

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

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

1、函數注釋

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

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

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

2、設計注釋

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

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

3、Why 注釋

解釋代碼為什么要做某事，即使代碼行為很清晰，這種注釋可能是思考系統改進的機會。

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

4、Teacher 注釋

教學代碼，對讀者有很大價值，能增加可閱讀代碼的程序員數量。

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

5、Checklist 注釋

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

這很像是對一個事務的解釋，一個事務會涉及到多個階段，但是每個階段要執行的東西可能會分散到各處，當你讀到其中的某個階段代碼時，如果有 Checklist 告知你整個事務鏈條，那你對這個事務會理解的更加清晰。

6、Guide 注釋

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

這更像是一個項目的 README 文件，好的開源項目一定有一個好的 README 文檔，告訴使用者需要什么環境、要安裝什么依賴包、如何配置參數、如何啟動等等。

7、瑣碎注釋

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

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

count++;	// 自增

8、債務注釋

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

有時候為了快速的實現功能，可能有些邏輯會有臨時性的快速方案，然后在對應的位置加上 TODO，之后可能臨時方案就變成最終方案了。

9、Backup 注釋

開發者對舊版本代碼塊或函數進行注釋，因對新代碼不放心，但這是不合適的，源代碼不是用來做備份的。

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

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

同樣是接手一份代碼，如果是沒有注釋的，我們在接手的時候就難免會先產生反感、畏難情緒，除非注釋是亂寫的。

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

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