Google C++Style Guide【C++程式設計風格指南解讀】——注釋

注釋雖然寫起來很痛苦, 但對保證代碼可讀性至關重要. 下面的規則描述了如何注釋以及在哪兒注釋. 當然也要記住: 注釋固然很重要, 但最好的代碼本身應該是自文檔化. 有意義的類型名和變量名, 要遠勝過要用注釋解釋的含糊不清的名字.

1：使用 // 或 , 統一就好.

解讀：個人覺得//會比較友善一點~

2：在每一個檔案開頭加入版權公告, 然後是檔案内容描述.

解讀：

每個檔案都應該包含以下項, 依次是:

1：版權聲明 (比如, Copyright 2008 Google Inc.)

2：許可證. 為項目選擇合适的許可證版本 (比如, Apache 2.0, BSD, LGPL, GPL)

3：作者: 辨別檔案的原始作者.

緊接着版權許可和作者資訊之後, 每個檔案都要用注釋描述檔案内容.

通常, .h 檔案要對所聲明的類的功能和用法作簡單說明. .cc 檔案通常包含了更多的實作細節或算法技巧讨論,如果你感覺這些實作細節或算法技巧讨論對于了解 .h 檔案有幫助, 可以将該注釋挪到 .h, 并在 .cc 中指出文檔在 .h.

不要簡單的在 .h 和 .cc 間複制注釋. 這種偏離了注釋的實際意義.

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：函數聲明處注釋描述函數功能; 定義處描述函數實作.

解讀：每個函數定義時要用注釋說明函數功能和實作要點. 比如說說你用的程式設計技巧, 實作的大緻步驟, 或解釋如此實作的理由, 為什麼前半部分要加鎖而後半部分不需要.——不要過于繁瑣~

5：通常變量名本身足以很好說明變量用途. 某些情況下, 也需要額外的注釋說明.

解讀：

情況1：類資料成員:每個類資料成員 (也叫執行個體變量或成員變量) 都應該用注釋說明用途. 如果變量可以接受 NULL 或 -1 等警戒值, 須加以說明. 比如:

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_;
           

情況2：全局變量:和資料成員一樣, 所有全局變量也要注釋說明含義及用途. 比如:

// The total number of tests cases that we run through in this regression test.
const int kNumTestCases = 6;
           

譯者 (YuleFox) 筆記

1：關于注釋風格，很多 C++ 的 coders 更喜歡行注釋, C coders 或許對塊注釋依然情有獨鐘, 或者在檔案頭大段大段的注釋時使用塊注釋;

2：檔案注釋可以炫耀你的成就, 也是為了捅了簍子别人可以找你;

3：注釋要言簡意赅, 不要拖沓備援, 複雜的東西簡單化和簡單的東西複雜化都是要被鄙視的;

4：對于 Chinese coders 來說, 用英文注釋還是用中文注釋, it is a problem, 但不管怎樣, 注釋是為了讓别人看懂, 難道是為了炫耀程式設計語言之外的你的母語或外語水準嗎；

5：注釋不要太亂, 适當的縮進才會讓人樂意看. 但也沒有必要規定注釋從第幾列開始 (我自己寫代碼的時候總喜歡這樣), UNIX/LINUX 下還可以約定是使用 tab 還是 space, 個人傾向于 space;

6：TODO 很不錯, 有時候, 注釋确實是為了标記一些未完成的或完成的不盡如人意的地方, 這樣一搜尋, 就知道還有哪些活要幹, 日志都省了.