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