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