如何寫好注釋，讓同事贊不絕口？
如果領(lǐng)導給你一個項目的源碼讓你閱讀，并理解重構(gòu)代碼，但里面一句注釋都沒有，我想這肯定是之前同事“刪庫跑路”了。
看一份源碼什么很重要？除了各種代碼規(guī)范之外，還有一個比較重要的就是注釋。
注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關(guān)重要，下面我們就以C/C++代碼規(guī)范注釋****為例，將描述如何注釋以及有哪些講究。
1、注釋風格
1. 總述
一般使用?//?或?/* */，只要統(tǒng)一就好。
2. 說明
//?或?/* */?都可以，但團隊要在如何注釋及注釋風格上確保統(tǒng)一。
2、文件注釋
1. 總述
在每一個文件開頭加入版權(quán)、作者、時間等描述。
文件注釋描述了該文件的內(nèi)容，如果一個文件只聲明，或?qū)崿F(xiàn)，或測試了一個對象，并且這個對象已經(jīng)在它的聲明處進行了詳細的注釋，那么就沒必要再加上文件注釋，除此之外的其他文件都需要文件注釋。
2. 說明
法律公告和作者信息：
每個文件都應該包含許可證引用。也要為項目選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)。
3. 文件內(nèi)容
如果一個?.h?文件聲明了多個概念, 則文件注釋應當對文件的內(nèi)容做一個大致的說明, 同時說明各概念之間的聯(lián)系。一個一到兩行的文件注釋就足夠了, 對于每個概念的詳細文檔應當放在各個概念中, 而不是文件注釋中。
不要在?.h?和?.cc?之間復制注釋, 這樣的注釋偏離了注釋的實際意義。
最后再舉個最簡單的實際例子：
/************************************************************************
*
*????Copyright??Copyright?2020?Google?Inc.
*????File?Name:?文件名
*????Description:?描述
*
*????Version:?V1.0
*????Author:?Your_Name
*????Create?Time:?2020-01-01
*
*************************************************************************/
3、函數(shù)注釋
1. 總述
函數(shù)聲明處的注釋描述函數(shù)功能; 定義處的注釋描述函數(shù)實現(xiàn)。
2. 說明
函數(shù)聲明：
基本上每個函數(shù)聲明處前都應當加上注釋, 描述函數(shù)的功能和用途。只有在函數(shù)的功能簡單而明顯時才能省略這些注釋(例如, 簡單的取值和設值函數(shù))。
比如：
/************************************************************************
*
*????函?數(shù)?名：函數(shù)名
*????函數(shù)功能：功能描述
*????輸入?yún)?shù)：void
*????輸出參數(shù)：void
*????返?回?值:??void
*
*????作????者：Your_Name
*????創(chuàng)建時間：2020-01-01
*????其他說明：無
*????修改信息：無
*
************************************************************************/
函數(shù)定義：
如果函數(shù)的實現(xiàn)過程中用到了很巧妙的方式, 那么在函數(shù)定義處應當加上解釋性的注釋。比如, 你所使用的編程技巧, 實現(xiàn)的大致步驟, 或解釋如此實現(xiàn)的理由。舉個例子, 你可以說明為什么函數(shù)的前半部分要加鎖而后半部分不需要。
不要?從?.h?文件或其他地方的函數(shù)聲明處直接復制注釋. 簡要重述函數(shù)功能是可以的, 但注釋重點要放在如何實現(xiàn)上。
4、變量注釋
1. 總述
通常變量名本身足以很好說明變量用途， 某些情況下, 也需要額外的注釋說明。
2. 說明
根據(jù)不同場景、不同修飾符，變量可以分為很多種類，總的來說變量分為全局變量、局部變量。
一般來說局部變量僅限于局部范圍，其含義相對簡單容易理解，只需要簡單注釋即可。
全局變量一般作用于多個文件，或者整個工程，因此，其含義相對更復雜，所以在注釋的時候，最好描述清楚其具體含義，就是盡量全面描述。
（提示：全局變量盡量少用）
5、拼寫注釋
1. 總述
可能一個變量、一個函數(shù)包含的意思非常復雜，需要多個單詞拼寫而成，此時對拼寫內(nèi)容就需要詳細注釋。
2. 說明
注釋的通常寫法是包含正確大小寫和結(jié)尾句號的完整敘述性語句。大多數(shù)情況下, 完整的句子比句子片段可讀性更高。短一點的注釋, 比如代碼行尾注釋, 可以隨意點, 但依然要注意風格的一致性。
同時，注釋中的拼寫、逗號也很重要。雖然被別人指出該用分號時卻用了逗號多少有些尷尬, 但清晰易讀的代碼還是很重要的。正確的標點, 拼寫和語法對此會有很大幫助
6、TODO 注釋
1. 總述
對那些臨時的, 短期的解決方案, 或已經(jīng)夠好但仍不完美的代碼使用?TODO?注釋。
TODO?注釋要使用全大寫的字符串?TODO, 在隨后的圓括號里寫上你的名字, 郵件地址, bug ID, 或其它身份標識和與這一?TODO?相關(guān)的 issue。主要目的是讓添加注釋的人 (也是可以請求提供更多細節(jié)的人) 可根據(jù)規(guī)范的?TODO?格式進行查找。添加?TODO?注釋并不一定意味著你要自己來修正, 因此當你加上帶有姓名的?TODO?時, 一般都是寫上自己的名字。
7、結(jié) 語
注釋固然很重要, 但最好的代碼應當本身就是文檔，有意義的類型名和變量名, 要遠勝過要用注釋解釋的含糊不清的名字。
你寫的注釋是給代碼閱讀者看的, 也就是下一個需要理解你代碼的人. 所以慷慨些吧, 下一個讀者可能就是你！
往期推薦
