如果領導給你一個專案的原始碼讓你閱讀，並理解重構程式碼，但裡面一句註釋都沒有，我想這肯定是之前同事“刪庫跑路”了。
看一份原始碼什麼很重要？除了各種程式碼規範之外，還有一個比較重要的就是註釋。
註釋雖然寫起來很痛苦, 但對保證程式碼可讀性至關重要，下面的將描述如何註釋以及在哪兒註釋。
註釋風格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）, 或是找個幫手.
修正好的程式碼應該不會再涉及棄用介面點了, 著實改用新介面點. 如果您不知從何下手, 可以找標記棄用註釋的當事人一起商量。
結語註釋固然很重要, 但最好的程式碼應當本身就是文件，有意義的型別名和變數名, 要遠勝過要用註釋解釋的含糊不清的名字。
你寫的註釋是給程式碼閱讀者看的, 也就是下一個需要理解你程式碼的人。所以慷慨些吧，下一個讀者可能就是你！