[導讀]看一份源碼什么很重要？除了各種代碼規范之外，代碼還有一個比較重要的規范就是注釋。

關注、注釋星標公眾號，有講不錯過精彩內容

編排 |?strongerHuang

微信公眾號：strongerHuang

如果領導給你一個項目的代碼源碼讓你閱讀，并理解重構代碼，規范但里面一句注釋都沒有，注釋我想這肯定是有講之前同事“刪庫跑路”了。

看一份源碼什么很重要？除了各種代碼規范之外，代碼還有一個比較重要的規范就是注釋。

注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關重要，注釋下面的有講將描述如何注釋以及在哪兒注釋。

strongerHuang

1

注釋風格

1.總述

一般使用?//?或?/*?*/，代碼只要統一就好。規范

2.說明

//?或?/*?*/?都可以，注釋但?//?更?常用，要在如何注釋及注釋風格上確保統一。

strongerHuang

2

文件注釋

1.總述

在每一個文件開頭加入版權、作者、時間等描述。

文件注釋描述了該文件的內容，如果一個文件只聲明，或實現，或測試了一個對象，并且這個對象已經在它的聲明處進行了詳細的注釋，那么就沒必要再加上文件注釋，除此之外的其他文件都需要文件注釋。

2.說明

法律公告和作者信息：

每個文件都應該包含許可證引用. 為項目選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)。

如果你對原始作者的文件做了重大修改，請考慮刪除原作者信息。

3.文件內容

如果一個?.h?文件聲明了多個概念, 則文件注釋應當對文件的內容做一個大致的說明, 同時說明各概念之間的聯系. 一個一到兩行的文件注釋就足夠了, 對于每個概念的詳細文檔應當放在各個概念中, 而不是文件注釋中。

不要在?.h?和?.cc?之間復制注釋, 這樣的注釋偏離了注釋的實際意義。

strongerHuang

3

函數注釋

1.總述

函數聲明處的注釋描述函數功能; 定義處的注釋描述函數實現。

2.說明

函數聲明：

基本上每個函數聲明處前都應當加上注釋, 描述函數的功能和用途. 只有在函數的功能簡單而明顯時才能省略這些注釋(例如, 簡單的取值和設值函數)。

比如：FreeRTOS創建任務函數申明：

函數定義：

如果函數的實現過程中用到了很巧妙的方式, 那么在函數定義處應當加上解釋性的注釋。比如, 你所使用的編程技巧, 實現的大致步驟, 或解釋如此實現的理由. 舉個例子, 你可以說明為什么函數的前半部分要加鎖而后半部分不需要。

不要?從?.h?文件或其他地方的函數聲明處直接復制注釋. 簡要重述函數功能是可以的, 但注釋重點要放在如何實現上。

strongerHuang

4

變量注釋

1.總述

通常變量名本身足以很好說明變量用途， 某些情況下, 也需要額外的注釋說明。

2.說明

根據不同場景、不同修飾符，變量可以分為很多種類，總的來說變量分為全局變量、局部變量。

一般來說局部變量僅限于局部范圍，其含義相對簡單容易理解，只需要簡單注釋即可。

全局變量一般作用于多個文件，或者整個工程，因此，其含義相對更復雜，所以在注釋的時候，最好描述清楚其具體含義，就是盡量全面描述。

（提示：全局變量盡量少用）

strongerHuang

5

拼寫注釋

1.總述

可能一個變量、一個函數包含的意思非常復雜，需要多個單詞拼寫而成，此時對拼寫內容就需要詳細注釋。

2.說明

注釋的通常寫法是包含正確大小寫和結尾句號的完整敘述性語句. 大多數情況下, 完整的句子比句子片段可讀性更高. 短一點的注釋, 比如代碼行尾注釋, 可以隨意點, 但依然要注意風格的一致性。

同時，注釋中的拼寫、逗號也很重要。雖然被別人指出該用分號時卻用了逗號多少有些尷尬, 但清晰易讀的代碼還是很重要的. 正確的標點, 拼寫和語法對此會有很大幫助

strongerHuang

6

TODO 注釋

1.總述

對那些臨時的, 短期的解決方案, 或已經夠好但仍不完美的代碼使用? TODO?注釋。

TODO?注釋要使用全大寫的字符串? TODO, 在隨后的圓括號里寫上你的名字, 郵件地址, bug ID, 或其它身份標識和與這一? TODO?相關的 issue. 主要目的是讓添加注釋的人 (也是可以請求提供更多細節的人) 可根據規范的? TODO?格式進行查找. 添加? TODO?注釋并不意味著你要自己來修正, 因此當你加上帶有姓名的? TODO?時, 一般都是寫上自己的名字。

strongerHuang

7

TODO 注釋

1.總述

通過棄用注釋（ DEPRECATED?comments）以標記某接口點已棄用.

您可以寫上包含全大寫的? DEPRECATED?的注釋, 以標記某接口為棄用狀態. 注釋可以放在接口聲明前, 或者同一行.

在? DEPRECATED?一詞后, 在括號中留下您的名字, 郵箱地址以及其他身份標識.

棄用注釋應當包涵簡短而清晰的指引, 以幫助其他人修復其調用點. 在 C++ 中, 你可以將一個棄用函數改造成一個內聯函數, 這一函數將調用新的接口.

僅僅標記接口為? DEPRECATED?并不會讓大家不約而同地棄用, 您還得親自主動修正調用點（callsites）, 或是找個幫手.

修正好的代碼應該不會再涉及棄用接口點了, 著實改用新接口點. 如果您不知從何下手, 可以找標記棄用注釋的當事人一起商量。

strongerHuang

8

結語

注釋固然很重要, 但最好的代碼應當本身就是文檔，有意義的類型名和變量名, 要遠勝過要用注釋解釋的含糊不清的名字。

你寫的注釋是給代碼閱讀者看的, 也就是下一個需要理解你代碼的人. 所以慷慨些吧, 下一個讀者可能就是你！

------------?END?------------

推薦閱讀：

C語言實現面向對象的原理

無MMU搶占式操作系統的搶占工作原理

Embedded Studio中使用ST-Link調試教程

關 注 微信公眾號『strongerHuang』，后臺回復“1024”查看更多內容，回復“加群”按規則加入技術交流群。

長按前往圖中包含的公眾號關注

點擊“ 閱讀原文”查看更多分享，歡迎點分享、收藏、點贊、在看。

免責聲明：本文內容由21ic獲得授權后發布，版權歸原作者所有，本平臺僅提供信息存儲服務。文章僅代表作者個人觀點，不代表本平臺立場，如有問題，請聯系我們，謝謝！