關(guān)注、星標(biāo)公眾號(hào)，不錯(cuò)過精彩內(nèi)容
如果領(lǐng)導(dǎo)給你一個(gè)項(xiàng)目的源碼讓你閱讀，并理解重構(gòu)代碼，但里面一句注釋都沒有，我想這肯定是之前同事“刪庫(kù)跑路”了。
看一份源碼什么很重要？除了各種代碼規(guī)范之外，還有一個(gè)比較重要的就是注釋。
注釋雖然寫起來很痛苦, 但對(duì)保證代碼可讀性至關(guān)重要，下面的將描述如何注釋以及在哪兒注釋。
1.總述
一般使用?//?或?/*?*/，只要統(tǒng)一就好。
2.說明
//?或?/*?*/?都可以，但?//?更?常用，要在如何注釋及注釋風(fēng)格上確保統(tǒng)一。
1.總述
在每一個(gè)文件開頭加入版權(quán)、作者、時(shí)間等描述。
文件注釋描述了該文件的內(nèi)容，如果一個(gè)文件只聲明，或?qū)崿F(xiàn)，或測(cè)試了一個(gè)對(duì)象，并且這個(gè)對(duì)象已經(jīng)在它的聲明處進(jìn)行了詳細(xì)的注釋，那么就沒必要再加上文件注釋，除此之外的其他文件都需要文件注釋。
每個(gè)文件都應(yīng)該包含許可證引用. 為項(xiàng)目選擇合適的許可證版本(比如, Apache 2.0, BSD, LGPL, GPL)。
如果你對(duì)原始作者的文件做了重大修改，請(qǐng)考慮刪除原作者信息。
如果一個(gè)?.h?文件聲明了多個(gè)概念, 則文件注釋應(yīng)當(dāng)對(duì)文件的內(nèi)容做一個(gè)大致的說明, 同時(shí)說明各概念之間的聯(lián)系. 一個(gè)一到兩行的文件注釋就足夠了, 對(duì)于每個(gè)概念的詳細(xì)文檔應(yīng)當(dāng)放在各個(gè)概念中, 而不是文件注釋中。
不要在?.h?和?.cc?之間復(fù)制注釋, 這樣的注釋偏離了注釋的實(shí)際意義。
1.總述
函數(shù)聲明處的注釋描述函數(shù)功能; 定義處的注釋描述函數(shù)實(shí)現(xiàn)。
基本上每個(gè)函數(shù)聲明處前都應(yīng)當(dāng)加上注釋, 描述函數(shù)的功能和用途. 只有在函數(shù)的功能簡(jiǎn)單而明顯時(shí)才能省略這些注釋(例如, 簡(jiǎn)單的取值和設(shè)值函數(shù))。
比如：FreeRTOS創(chuàng)建任務(wù)函數(shù)申明：
如果函數(shù)的實(shí)現(xiàn)過程中用到了很巧妙的方式, 那么在函數(shù)定義處應(yīng)當(dāng)加上解釋性的注釋。比如, 你所使用的編程技巧, 實(shí)現(xiàn)的大致步驟, 或解釋如此實(shí)現(xiàn)的理由. 舉個(gè)例子, 你可以說明為什么函數(shù)的前半部分要加鎖而后半部分不需要。
不要?從?.h?文件或其他地方的函數(shù)聲明處直接復(fù)制注釋. 簡(jiǎn)要重述函數(shù)功能是可以的, 但注釋重點(diǎn)要放在如何實(shí)現(xiàn)上。
1.總述
通常變量名本身足以很好說明變量用途， 某些情況下, 也需要額外的注釋說明。
根據(jù)不同場(chǎng)景、不同修飾符，變量可以分為很多種類，總的來說變量分為全局變量、局部變量。
一般來說局部變量?jī)H限于局部范圍，其含義相對(duì)簡(jiǎn)單容易理解，只需要簡(jiǎn)單注釋即可。
全局變量一般作用于多個(gè)文件，或者整個(gè)工程，因此，其含義相對(duì)更復(fù)雜，所以在注釋的時(shí)候，最好描述清楚其具體含義，就是盡量全面描述。
1.總述
可能一個(gè)變量、一個(gè)函數(shù)包含的意思非常復(fù)雜，需要多個(gè)單詞拼寫而成，此時(shí)對(duì)拼寫內(nèi)容就需要詳細(xì)注釋。
注釋的通常寫法是包含正確大小寫和結(jié)尾句號(hào)的完整敘述性語(yǔ)句. 大多數(shù)情況下, 完整的句子比句子片段可讀性更高. 短一點(diǎn)的注釋, 比如代碼行尾注釋, 可以隨意點(diǎn), 但依然要注意風(fēng)格的一致性。
同時(shí)，注釋中的拼寫、逗號(hào)也很重要。雖然被別人指出該用分號(hào)時(shí)卻用了逗號(hào)多少有些尷尬, 但清晰易讀的代碼還是很重要的. 正確的標(biāo)點(diǎn), 拼寫和語(yǔ)法對(duì)此會(huì)有很大幫助
1.總述
對(duì)那些臨時(shí)的, 短期的解決方案, 或已經(jīng)夠好但仍不完美的代碼使用?
TODO
?注釋。
TODO
?注釋要使用全大寫的字符串?
TODO
, 在隨后的圓括號(hào)里寫上你的名字, 郵件地址, bug ID, 或其它身份標(biāo)識(shí)和與這一?
TODO
?相關(guān)的 issue. 主要目的是讓添加注釋的人 (也是可以請(qǐng)求提供更多細(xì)節(jié)的人) 可根據(jù)規(guī)范的?
TODO
?格式進(jìn)行查找. 添加?
TODO
?注釋并不意味著你要自己來修正, 因此當(dāng)你加上帶有姓名的?
TODO
?時(shí), 一般都是寫上自己的名字。
1.總述
通過棄用注釋（
DEPRECATED
?comments）以標(biāo)記某接口點(diǎn)已棄用.
您可以寫上包含全大寫的?
DEPRECATED
?的注釋, 以標(biāo)記某接口為棄用狀態(tài). 注釋可以放在接口聲明前, 或者同一行.
在?
DEPRECATED
?一詞后, 在括號(hào)中留下您的名字, 郵箱地址以及其他身份標(biāo)識(shí).
棄用注釋應(yīng)當(dāng)包涵簡(jiǎn)短而清晰的指引, 以幫助其他人修復(fù)其調(diào)用點(diǎn). 在 C++ 中, 你可以將一個(gè)棄用函數(shù)改造成一個(gè)內(nèi)聯(lián)函數(shù), 這一函數(shù)將調(diào)用新的接口.
僅僅標(biāo)記接口為?
DEPRECATED
?并不會(huì)讓大家不約而同地棄用, 您還得親自主動(dòng)修正調(diào)用點(diǎn)（callsites）, 或是找個(gè)幫手.
修正好的代碼應(yīng)該不會(huì)再涉及棄用接口點(diǎn)了, 著實(shí)改用新接口點(diǎn). 如果您不知從何下手, 可以找標(biāo)記棄用注釋的當(dāng)事人一起商量。
注釋固然很重要, 但最好的代碼應(yīng)當(dāng)本身就是文檔，有意義的類型名和變量名, 要遠(yuǎn)勝過要用注釋解釋的含糊不清的名字。
你寫的注釋是給代碼閱讀者看的, 也就是下一個(gè)需要理解你代碼的人. 所以慷慨些吧, 下一個(gè)讀者可能就是你！
------------?END?------------
C語(yǔ)言實(shí)現(xiàn)面向?qū)ο蟮脑?/strong>
無(wú)MMU搶占式操作系統(tǒng)的搶占工作原理
Embedded Studio中使用ST-Link調(diào)試教程
關(guān)
注
微信公眾號(hào)『strongerHuang』，后臺(tái)回復(fù)“1024”查看更多內(nèi)容，回復(fù)“加群”按規(guī)則加入技術(shù)交流群。
長(zhǎng)按前往圖中包含的公眾號(hào)關(guān)注
點(diǎn)擊“
閱讀原文
”查看更多分享，歡迎點(diǎn)分享、收藏、點(diǎn)贊、在看。
下載文檔
