初學編程要注重寫註釋，爲你說明代碼規範註釋有哪些講究

來自公衆號：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界面開發、黑客等等......