C++編碼規(guī)范之代碼注釋
注釋雖然寫起來痛苦但對保證代碼可讀性至為重要。
1.注釋風(fēng)格
使用// 或/**/統(tǒng)一就好
2.文件注釋
在每一個(gè)文件開頭加入版權(quán)公告,然后是文件內(nèi)容描述
法律公告和作者信息
每一文件包含以下項(xiàng)依次是:
1)版權(quán)(copyright statement)
2)許可版本(license boilerplate)
3)作者(author line)：標(biāo)識文件原始作者
.h文件要多所生命的類的功能和用法做簡單說名
.cc文件包含了更多的實(shí)現(xiàn)細(xì)節(jié)或算法討論。
3.類注釋
每一類的定義要附著描述類的功能和用法的注釋
//Iterates over the contents of a GargantuanTable.Sample usage
// GargantuanTable_Iterator* iter = table->newIterator()
// for(iter->Seek("foo");!iter->done();iter->Next()){
// process(iter->key(),iter->value());
// }
//delete iter;
class GargantuanTable_Iterator{
...
};
4.函數(shù)注釋
函數(shù)聲明處注釋描述函數(shù)功能,定義處描述函數(shù)實(shí)現(xiàn)
函數(shù)聲明:
注釋于聲明之前,描述函數(shù)功能及用法,注釋使用描述式.
函數(shù)聲明處注釋的內(nèi)容:
1)inputs(輸入)及outputs(輸出)
2)對類成員函數(shù)而言:函數(shù)調(diào)用期間對象是否需要保持引用參數(shù),是否會(huì)釋放這些參數(shù)
3.如果函數(shù)分配了空間,需要由調(diào)用者釋放
4.參數(shù)是否可以是NULL
5.是否存在函數(shù)使用性能隱憂(performance implications)
6.如果函數(shù)是可重入的其同步前提是什么
函數(shù)定義
每個(gè)函數(shù)定義時(shí)要以注釋說明函數(shù)的功能和實(shí)現(xiàn)要點(diǎn)。
5.變量注釋
變量名本身足以很好說明變量用途,特定情況下,需要額外注釋說明
類數(shù)據(jù)成員
每個(gè)類數(shù)據(jù)成員應(yīng)注釋說明用途。如果變量可以接收NULL,-1等警戒值
6.實(shí)現(xiàn)注釋
對于實(shí)現(xiàn)代碼中巧妙的,晦澀的,有趣的,重要的地方加以注釋。
7.標(biāo)點(diǎn),拼寫和語法
留意標(biāo)點(diǎn),拼寫和語法,寫得好的注釋要比差的易讀的多
8.TODO注釋
對那些臨時(shí)的,短期的解決方案或已經(jīng)夠好但并不完美的代碼使用TODO注釋
