原文地址：Google C++ Style Guide
注釋雖然寫起來很痛苦，但對(duì)保證代碼可讀性至為重要，下面的規(guī)則描述了應(yīng)該注釋什么、注釋在哪兒。當(dāng)然也要記住，注釋的確很重要，但最好的代碼本身就是文檔（self-documenting），類型和變量命名意義明確要比通過注釋解釋模糊的命名好得多。
注釋是為別人（下一個(gè)需要理解你的代碼的人）而寫的，認(rèn)真點(diǎn)吧，那下一個(gè)人可能就是你！
1. 注釋風(fēng)格（Comment Style）
使用//或/* */，統(tǒng)一就好。
//或/* */都可以，//只是用的更加廣泛，在如何注釋和注釋風(fēng)格上確保統(tǒng)一。
2. 文件注釋（File Comments）
在每一個(gè)文件開頭加入版權(quán)公告，然后是文件內(nèi)容描述。
法律公告和作者信息：
每一文件包含以下項(xiàng)，依次是：
1) 版權(quán)（copyright statement）：如Copyright 2008 Google Inc.；
2) 許可版本（license boilerplate）：為項(xiàng)目選擇合適的許可證版本，如Apache 2.0、BSD、LGPL、GPL；
3) 作者（author line）：標(biāo)識(shí)文件的原始作者。
如果你對(duì)其他人創(chuàng)建的文件做了重大修改，將你的信息添加到作者信息里，這樣當(dāng)其他人對(duì)該文件有疑問時(shí)可以知道該聯(lián)系誰。
文件內(nèi)容：
每一個(gè)文件版權(quán)許可及作者信息后，都要對(duì)文件內(nèi)容進(jìn)行注釋說明。
通常，.h文件要對(duì)所聲明的類的功能和用法作簡單說明，.cc文件包含了更多的實(shí)現(xiàn)細(xì)節(jié)或算法討論，如果你感覺這些實(shí)現(xiàn)細(xì)節(jié)或算法討論對(duì)于閱讀有幫助，可以把.cc中的注釋放到.h中，并在.cc中指出文檔在.h中。
不要單純在.h和.cc間復(fù)制注釋，復(fù)制的注釋偏離了實(shí)際意義。
3. 類注釋（Class Comments）
每個(gè)類的定義要附著描述類的功能和用法的注釋。
// 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 {
...
};
如果你覺得已經(jīng)在文件頂部詳細(xì)描述了該類，想直接簡單的來上一句“完整描述見文件頂部”的話，還是多少在類中加點(diǎn)注釋吧。
如果類有任何同步前提（synchronization assumptions），文檔說明之。如果該類的實(shí)例可被多線程訪問，使用時(shí)務(wù)必注意文檔說明。
4. 函數(shù)注釋（Function Comments）
函數(shù)聲明處注釋描述函數(shù)功能，定義處描述函數(shù)實(shí)現(xiàn)。
函數(shù)聲明：
注釋于聲明之前，描述函數(shù)功能及用法，注釋使用描述式（"Opens the file"）而非指令式（"Open the file"）；注釋只是為了描述函數(shù)而不是告訴函數(shù)做什么。通常，注釋不會(huì)描述函數(shù)如何實(shí)現(xiàn)，那是定義部分的事情。
函數(shù)聲明處注釋的內(nèi)容：
1) inputs（輸入）及outputs（輸出）；
2) 對(duì)類成員函數(shù)而言：函數(shù)調(diào)用期間對(duì)象是否需要保持引用參數(shù)，是否會(huì)釋放這些參數(shù)；
3) 如果函數(shù)分配了空間，需要由調(diào)用者釋放；
4) 參數(shù)是否可以為NULL；
5) 是否存在函數(shù)使用的性能隱憂（performance implications）；
6) 如果函數(shù)是可重入的（re-entrant），其同步前提（synchronization assumptions）是什么？
舉例如下：
// Returns an iterator for this table. It is the client's
// responsibility to delete the iterator when it is done with it,
// and it must not use the iterator once the GargantuanTable object
// on which the iterator was created has been deleted.
//
// The iterator is initially positioned at the beginning of the table.
//
// This method is equivalent to:
// Iterator* iter = table->NewIterator();
// iter->Seek("");
// return iter;
// If you are going to immediately seek to another place in the
// returned iterator, it will be faster to use NewIterator()
// and avoid the extra seek.
Iterator* GetIterator() const;
但不要有無謂冗余或顯而易見的注釋，下面的注釋就沒有必要加上“returns false otherwise”，因?yàn)橐呀?jīng)暗含其中了：
// Returns true if the table cannot hold any more entries.
bool IsTableFull();
注釋構(gòu)造/析構(gòu)函數(shù)時(shí)，記住，讀代碼的人知道構(gòu)造/析構(gòu)函數(shù)是什么，所以“destroys this object”這樣的注釋是沒有意義的。說明構(gòu)造函數(shù)對(duì)參數(shù)做了什么（例如，是否是指針的所有者）以及析構(gòu)函數(shù)清理了什么，如果都是無關(guān)緊要的內(nèi)容，直接省掉注釋，析構(gòu)函數(shù)前沒有注釋是很正常的。
函數(shù)定義：
每個(gè)函數(shù)定義時(shí)要以注釋說明函數(shù)功能和實(shí)現(xiàn)要點(diǎn)，如使用的漂亮代碼、實(shí)現(xiàn)的簡要步驟、如此實(shí)現(xiàn)的理由、為什么前半部分要加鎖而后半部分不需要。
不要從.h文件或其他地方的函數(shù)聲明處直接復(fù)制注釋，簡要說明函數(shù)功能是可以的，但重點(diǎn)要放在如何實(shí)現(xiàn)上。
5. 變量注釋（Variable Comments）
通常變量名本身足以很好說明變量用途，特定情況下，需要額外注釋說明。
類數(shù)據(jù)成員：
每個(gè)類數(shù)據(jù)成員（也叫實(shí)例變量或成員變量）應(yīng)注釋說明用途，如果變量可以接受NULL或-1等警戒值（sentinel values），須說明之，如：
private:
// Keeps track of the total number of entries in the table.
// Used to ensure we do not go over the limit. -1 means
// that we don't yet know how many entries the table has.
int num_total_entries_;
全局變量（常量）：
和數(shù)據(jù)成員相似，所有全局變量（常量）也應(yīng)注釋說明含義及用途，如：
// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;
6. 實(shí)現(xiàn)注釋（Implementation Comments）
對(duì)于實(shí)現(xiàn)代碼中巧妙的、晦澀的、有趣的、重要的地方加以注釋。
代碼前注釋：
出彩的或復(fù)雜的代碼塊前要加注釋，如：
// Divide result by two, taking into account that x
// contains the carry from the add.
for (int i = 0; i < result->size(); i++) {
x = (x << 8) + (*result)[i];
(*result)[i] = x >> 1;
x &= 1;
}
行注釋：
比較隱晦的地方要在行尾加入注釋，可以在代碼之后空兩格加行尾注釋，如：
// If we have enough memory, mmap the data portion too.
mmap_budget = max<int64>(0, mmap_budget - index_->length());
if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock))
return; // Error already logged.
注意，有兩塊注釋描述這段代碼，當(dāng)函數(shù)返回時(shí)注釋提及錯(cuò)誤已經(jīng)被記入日志。
前后相鄰幾行都有注釋，可以適當(dāng)調(diào)整使之可讀性更好：
...
DoSomething(); // Comment here so the comments line up.
DoSomethingElseThatIsLonger(); // Comment here so there are two spaces between
// the code and the comment.
...
NULL、true/false、1、2、3……：
向函數(shù)傳入、布爾值或整數(shù)時(shí)，要注釋說明含義，或使用常量讓代碼望文知意，比較一下：
bool success = CalculateSomething(interesting_value,
10,
false,
NULL); // What are these arguments??
和：
bool success = CalculateSomething(interesting_value,
10, // Default base value.
false, // Not the first time we're calling this.
NULL); // No callback.
使用常量或描述性變量：
const int kDefaultBaseValue = 10;
const bool kFirstTimeCalling = false;
Callback *null_callback = NULL;
bool success = CalculateSomething(interesting_value,
kDefaultBaseValue,
kFirstTimeCalling,
null_callback);
不要：
注意永遠(yuǎn)不要用自然語言翻譯代碼作為注釋，要假設(shè)讀你代碼的人C++比你強(qiáng):D：
// Now go through the b array and make sure that if i occurs,
// the next element is i+1.
... // Geez. What a useless comment.
7. 標(biāo)點(diǎn)、拼寫和語法（Punctuation, Spelling and Grammar）
留意標(biāo)點(diǎn)、拼寫和語法，寫的好的注釋比差的要易讀的多。
注釋一般是包含適當(dāng)大寫和句點(diǎn)（.）的完整的句子，短一點(diǎn)的注釋（如代碼行尾的注釋）可以隨意點(diǎn)，依然要注意風(fēng)格的一致性。完整的句子可讀性更好，也可以說明該注釋是完整的而不是一點(diǎn)不成熟的想法。
雖然被別人指出該用分號(hào)（semicolon）的時(shí)候用了逗號(hào)（comma）有點(diǎn)尷尬。清晰易讀的代碼還是很重要的，適當(dāng)?shù)臉?biāo)點(diǎn)、拼寫和語法對(duì)此會(huì)有所幫助。
8. TODO注釋（TODO Comments）
對(duì)那些臨時(shí)的、短期的解決方案，或已經(jīng)夠好但并不完美的代碼使用TODO注釋。
這樣的注釋要使用全大寫的字符串TODO，后面括號(hào)（parentheses）里加上你的大名、郵件地址等，還可以加上冒號(hào)（colon）：目的是可以根據(jù)統(tǒng)一的TODO格式進(jìn)行查找：
// TODO(kl@gmail.com): Use a "*" here for concatenation operator.
// TODO(Zeke) change this to use relations.
如果加上是為了在“將來某一天做某事”，可以加上一個(gè)特定的時(shí)間（"Fix by November 2005"）或事件（"Remove this code when all clients can handle XML responses."）。
______________________________________
譯者：注釋也是比較人性化的約定了：
1. 關(guān)于注釋風(fēng)格，很多C++的coders更喜歡行注釋，C coders或許對(duì)塊注釋依然情有獨(dú)鐘，或者在文件頭大段大段的注釋時(shí)使用塊注釋；
2. 文件注釋可以炫耀你的成就，也是為了捅了簍子別人可以找你；
3. 注釋要言簡意賅，不要拖沓冗余，復(fù)雜的東西簡單化和簡單的東西復(fù)雜化都是要被鄙視的；
4. 對(duì)于Chinese coders來說，用英文注釋還是用中文注釋，it is a problem，但不管怎樣，注釋是為了讓別人看懂，難道是為了炫耀編程語言之外的你的母語或外語水平嗎；
5. 注釋不要太亂，適當(dāng)?shù)目s進(jìn)才會(huì)讓人樂意看，但也沒有必要規(guī)定注釋從第幾列開始（我自己寫代碼的時(shí)候總喜歡這樣），UNIX/LINUX下還可以約定是使用tab還是space，個(gè)人傾向于space；
6. TODO很不錯(cuò)，有時(shí)候，注釋確實(shí)是為了標(biāo)記一些未完成的或完成的不盡如人意的地方，這樣一搜索，就知道還有哪些活要干，日志都省了。