來自公眾號：strongerHuang
如果領導給你一個專案的原始碼讓你閱讀，并理解重構代碼，但里面一句注釋都沒有，我想這肯定是之前同事“刪庫跑路”了，
看一份原始碼什么很重要？除了各種代碼規范之外，還有一個比較重要的就是注釋，
注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關重要，下面的將描述如何注釋以及在哪兒注釋，
注釋風格
1.總述
一般使用 // 或 /* */，只要統一就好，
2.說明
// 或 /* */ 都可以，但 // 更 常用，要在如何注釋及注釋風格上確保統一，
檔案注釋
1.總述
在每一個檔案開頭加入著作權、作者、時間等描述，
檔案注釋描述了該檔案的內容，如果一個檔案只宣告，或實作，或測驗了一個物件，并且這個物件已經在它的宣告處進行了詳細的注釋，那么就沒必要再加上檔案注釋，除此之外的其他檔案都需要檔案注釋，
2.說明
法律公告和作者資訊：
每個檔案都應該包含許可證參考. 為專案選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)，
如果你對原始作者的檔案做了重大修改，請考慮洗掉原作者資訊，
3.檔案內容
如果一個 .h 檔案宣告了多個概念, 則檔案注釋應當對檔案的內容做一個大致的說明, 同時說明各概念之間的聯系. 一個一到兩行的檔案注釋就足夠了, 對于每個概念的詳細檔案應當放在各個概念中, 而不是檔案注釋中，
不要在 .h 和 .cc 之間復制注釋, 這樣的注釋偏離了注釋的實際意義，
函式注釋
1.總述
函式宣告處的注釋描述函式功能; 定義處的注釋描述函式實作，
2.說明
函式宣告：
基本上每個函式宣告處前都應當加上注釋, 描述函式的功能和用途. 只有在函式的功能簡單而明顯時才能省略這些注釋(例如, 簡單的取值和設值函式)，
比如：FreeRTOS創建任務函式申明：
函式定義：
如果函式的實作程序中用到了很巧妙的方式, 那么在函式定義處應當加上解釋性的注釋，比如, 你所使用的編程技巧, 實作的大致步驟, 或解釋如此實作的理由. 舉個例子, 你可以說明為什么函式的前半部分要加鎖而后半部分不需要，
不要 從 .h 檔案或其他地方的函式宣告處直接復制注釋. 簡要重述函式功能是可以的, 但注釋重點要放在如何實作上，
變數注釋
1.總述
通常變數名本身足以很好說明變數用途， 某些情況下, 也需要額外的注釋說明，
2.說明
根據不同場景、不同修飾符，變數可以分為很多種類，總的來說變數分為全域變數、區域變數，
一般來說區域變數僅限于區域范圍，其含義相對簡單容易理解，只需要簡單注釋即可，
全域變數一般作用于多個檔案，或者整個工程，因此，其含義相對更復雜，所以在注釋的時候，最好描述清楚其具體含義，就是盡量全面描述，
（提示：全域變數盡量少用）
拼寫注釋
1.總述
可能一個變數、一個函式包含的意思非常復雜，需要多個單詞拼寫而成，此時對拼寫內容就需要詳細注釋，
2.說明
注釋的通常寫法是包含正確大小寫和結尾句號的完整敘述性陳述句. 大多數情況下, 完整的句子比句子片段可讀性更高. 短一點的注釋, 比如代碼行尾注釋, 可以隨意點, 但依然要注意風格的一致性，
同時，注釋中的拼寫、逗號也很重要，雖然被別人指出該用分號時卻用了逗號多少有些尷尬, 但清晰易讀的代碼還是很重要的. 正確的標點, 拼寫和語法對此會有很大幫助
TODO 注釋
1.總述
對那些臨時的, 短期的解決方案, 或已經夠好但仍不完美的代碼使用 TODO 注釋，
TODO 注釋要使用全大寫的字串 TODO, 在隨后的圓括號里寫上你的名字, 郵件地址, bug ID, 或其它身份標識和與這一 TODO 相關的 issue. 主要目的是讓添加注釋的人 (也是可以請求提供更多細節的人) 可根據規范的 TODO 格式進行查找. 添加 TODO 注釋并不意味著你要自己來修正, 因此當你加上帶有姓名的 TODO 時, 一般都是寫上自己的名字，
1.總述
通過棄用注釋（DEPRECATED comments）以標記某介面點已棄用.
您可以寫上包含全大寫的 DEPRECATED 的注釋, 以標記某介面為棄用狀態. 注釋可以放在介面宣告前, 或者同一行.
在 DEPRECATED 一詞后, 在括號中留下您的名字, 郵箱地址以及其他身份標識.
棄用注釋應當包涵簡短而清晰的指引, 以幫助其他人修復其呼叫點. 在 C++ 中, 你可以將一個棄用函式改造成一個行內函式, 這一函式將呼叫新的介面.
僅僅標記介面為 DEPRECATED 并不會讓大家不約而同地棄用, 您還得親自主動修正呼叫點（callsites）, 或是找個幫手.
修正好的代碼應該不會再涉及棄用介面點了, 著實改用新介面點. 如果您不知從何下手, 可以找標記棄用注釋的當事人一起商量，
結語
注釋固然很重要, 但最好的代碼應當本身就是檔案，有意義的型別名和變數名, 要遠勝過要用注釋解釋的含糊不清的名字，
你寫的注釋是給代碼閱讀者看的, 也就是下一個需要理解你代碼的人，所以慷慨些吧，下一個讀者可能就是你！
如果你對C/C++感興趣，想學編程，小編推薦一個C/C++技術交流群【點擊進入】！
涉及到了：編程入門、游戲編程、網路編程、Windows編程、Linux編程、Qt界面開發、黑客等等......
轉載請註明出處，本文鏈接：https://www.uj5u.com/houduan/240744.html
標籤：C
上一篇：鏈表調通