Google編程風(fēng)格指南(一）

0. 扉頁(yè)

0.1 譯者前言

Google 經(jīng)常會(huì)發(fā)布一些開(kāi)源項(xiàng)目, 意味著會(huì)接受來(lái)自其他代碼貢獻(xiàn)者的代碼. 但是如果代碼貢獻(xiàn)者的編程風(fēng)格與 Google 的不一致, 會(huì)給代碼閱讀者和其他代碼提交者造成不小的困擾. Google 因此發(fā)布了這份自己的編程風(fēng)格指南, 使所有提交代碼的人都能獲知 Google 的編程風(fēng)格.

翻譯初衷:

規(guī)則的作用就是避免混亂. 但規(guī)則本身一定要權(quán)威, 有說(shuō)服力, 并且是理性的. 我們所見(jiàn)過(guò)的大部分編程規(guī)范, 其內(nèi)容或不夠嚴(yán)謹(jǐn), 或闡述過(guò)于簡(jiǎn)單, 或帶有一定的武斷性.

Google 保持其一貫的嚴(yán)謹(jǐn)精神, 5 萬(wàn)漢字的指南涉及廣泛, 論證嚴(yán)密. 我們翻譯該系列指南的主因也正是其嚴(yán)謹(jǐn)性. 嚴(yán)謹(jǐn)意味著指南的價(jià)值不僅僅局限于它羅列出的規(guī)范, 更具參考意義的是它為了列出規(guī)范而做的謹(jǐn)慎權(quán)衡過(guò)程.

指南不僅列出你要怎么做, 還告訴你為什么要這么做, 哪些情況下可以不這么做, 以及如何權(quán)衡其利弊. 其他團(tuán)隊(duì)未必要完全遵照指南亦步亦趨, 如前面所說(shuō), 這份指南是 Google 根據(jù)自身實(shí)際情況打造的, 適用于其主導(dǎo)的開(kāi)源項(xiàng)目. 其他團(tuán)隊(duì)可以參照該指南, 或從中汲取靈感, 建立適合自身實(shí)際情況的規(guī)范.

我們?cè)诜g的過(guò)程中, 收獲頗多. 希望本系列指南中文版對(duì)你同樣能有所幫助.

我們翻譯時(shí)也是盡力保持嚴(yán)謹(jǐn), 但水平所限, bug 在所難免. 有任何意見(jiàn)或建議, 可與我們?nèi)〉寐?lián)系.

中文版和英文版一樣, 使用ArtisticLicense/GPL開(kāi)源許可.

中文版修訂歷史:

2015-08 : 熱心的清華大學(xué)同學(xué) @lilinsanity 完善了「類」章節(jié)以及其它一些小章節(jié)。至此，對(duì) Google CPP Style Guide 4.45 的翻譯正式竣工。

2015-07 4.45 : acgtyrant 為了學(xué)習(xí) C++ 的規(guī)范，順便重新翻譯了本 C++ 風(fēng)格指南，特別是 C++11 的全新內(nèi)容。排版大幅度優(yōu)化，翻譯措辭更地道，添加了新譯者筆記。Google 總部 C++ 工程師 innocentim, 清華大學(xué)不愿意透露姓名的唐馬儒先生，大阪大學(xué)大學(xué)院情報(bào)科學(xué)研究科計(jì)算機(jī)科學(xué)專攻博士 farseerfc 和其它 Arch Linux 中文社區(qū)眾幫了譯者不少忙，謝謝他們。因?yàn)?C++ Primer 尚未完全入門(mén)，暫時(shí)沒(méi)有翻譯「類」章節(jié)和其它一些小章節(jié)。

2009-06 3.133 : YuleFox 的 1.0 版已經(jīng)相當(dāng)完善, 但原版在近一年的時(shí)間里, 其規(guī)范也發(fā)生了一些變化.

Yang.Y 與 YuleFox 一拍即合, 以項(xiàng)目的形式來(lái)延續(xù)中文版 :Google 開(kāi)源項(xiàng)目風(fēng)格指南 - 中文版項(xiàng)目.

主要變化是同步到 3.133 最新英文版本, 做部分勘誤和改善可讀性方面的修改, 并改進(jìn)排版效果. Yang.Y 重新翻修, YuleFox 做后續(xù)評(píng)審.

2008-07 1.0 : 出自YuleFox 的 Blog, 很多地方摘錄的也是該版本.

0.2 背景

C++ 是 Google 大部分開(kāi)源項(xiàng)目的主要編程語(yǔ)言. 正如每個(gè) C++ 程序員都知道的, C++ 有很多強(qiáng)大的特性, 但這種強(qiáng)大不可避免的導(dǎo)致它走向復(fù)雜，使代碼更容易產(chǎn)生 bug, 難以閱讀和維護(hù).

本指南的目的是通過(guò)詳細(xì)闡述 C++ 注意事項(xiàng)來(lái)駕馭其復(fù)雜性. 這些規(guī)則在保證代碼易于管理的同時(shí), 也能高效使用 C++ 的語(yǔ)言特性.

風(fēng)格, 亦被稱作可讀性, 也就是指導(dǎo) C++ 編程的約定. 使用術(shù)語(yǔ) “風(fēng)格” 有些用詞不當(dāng), 因?yàn)檫@些習(xí)慣遠(yuǎn)不止源代碼文件格式化這么簡(jiǎn)單.

使代碼易于管理的方法之一是加強(qiáng)代碼一致性. 讓任何程序員都可以快速讀懂你的代碼這點(diǎn)非常重要. 保持統(tǒng)一編程風(fēng)格并遵守約定意味著可以很容易根據(jù) “模式匹配” 規(guī)則來(lái)推斷各種標(biāo)識(shí)符的含義. 創(chuàng)建通用, 必需的習(xí)慣用語(yǔ)和模式可以使代碼更容易理解. 在一些情況下可能有充分的理由改變某些編程風(fēng)格, 但我們還是應(yīng)該遵循一致性原則，盡量不這么做.

本指南的另一個(gè)觀點(diǎn)是 C++ 特性的臃腫. C++ 是一門(mén)包含大量高級(jí)特性的龐大語(yǔ)言. 某些情況下, 我們會(huì)限制甚至禁止使用某些特性. 這么做是為了保持代碼清爽, 避免這些特性可能導(dǎo)致的各種問(wèn)題. 指南中列舉了這類特性, 并解釋為什么這些特性被限制使用.

Google 主導(dǎo)的開(kāi)源項(xiàng)目均符合本指南的規(guī)定.

注意: 本指南并非 C++ 教程, 我們假定讀者已經(jīng)對(duì) C++ 非常熟悉.

1. 頭文件

通常每一個(gè).cc文件都有一個(gè)對(duì)應(yīng)的.h文件. 也有一些常見(jiàn)例外, 如單元測(cè)試代碼和只包含main()函數(shù)的.cc文件.

正確使用頭文件可令代碼在可讀性、文件大小和性能上大為改觀.

下面的規(guī)則將引導(dǎo)你規(guī)避使用頭文件時(shí)的各種陷阱.

1.1. Self-contained 頭文件

Tip

頭文件應(yīng)該能夠自給自足（self-contained,也就是可以作為第一個(gè)頭文件被引入），以.h結(jié)尾。至于用來(lái)插入文本的文件，說(shuō)到底它們并不是頭文件，所以應(yīng)以.inc結(jié)尾。不允許分離出-inl.h頭文件的做法.

所有頭文件要能夠自給自足。換言之，用戶和重構(gòu)工具不需要為特別場(chǎng)合而包含額外的頭文件。詳言之，一個(gè)頭文件要有1.2. #define 保護(hù)，統(tǒng)統(tǒng)包含它所需要的其它頭文件，也不要求定義任何特別 symbols.

不過(guò)有一個(gè)例外，即一個(gè)文件并不是 self-contained 的，而是作為文本插入到代碼某處?；蛘?，文件內(nèi)容實(shí)際上是其它頭文件的特定平臺(tái)（platform-specific）擴(kuò)展部分。這些文件就要用.inc文件擴(kuò)展名。

如果.h文件聲明了一個(gè)模板或內(nèi)聯(lián)函數(shù)，同時(shí)也在該文件加以定義。凡是有用到這些的.cc文件，就得統(tǒng)統(tǒng)包含該頭文件，否則程序可能會(huì)在構(gòu)建中鏈接失敗。不要把這些定義放到分離的-inl.h文件里（譯者注：過(guò)去該規(guī)范曾提倡把定義放到 -inl.h 里過(guò)）。

有個(gè)例外：如果某函數(shù)模板為所有相關(guān)模板參數(shù)顯式實(shí)例化，或本身就是某類的一個(gè)私有成員，那么它就只能定義在實(shí)例化該模板的.cc文件里。

1.2. #define 保護(hù)

Tip

所有頭文件都應(yīng)該使用#define來(lái)防止頭文件被多重包含, 命名格式當(dāng)是:___H_.

為保證唯一性, 頭文件的命名應(yīng)該基于所在項(xiàng)目源代碼樹(shù)的全路徑. 例如, 項(xiàng)目foo中的頭文件foo/src/bar/baz.h可按如下方式保護(hù):

#ifndef FOO_BAR_BAZ_H_#define FOO_BAR_BAZ_H_...#endif // FOO_BAR_BAZ_H_

1.3. 前置聲明

Tip

盡可能地避免使用前置聲明。使用#include包含需要的頭文件即可。

定義：

所謂「前置聲明」（forward declaration）是類、函數(shù)和模板的純粹聲明，沒(méi)伴隨著其定義.

優(yōu)點(diǎn)：

前置聲明能夠節(jié)省編譯時(shí)間，多余的#include會(huì)迫使編譯器展開(kāi)更多的文件，處理更多的輸入。

前置聲明能夠節(jié)省不必要的重新編譯的時(shí)間。#include使代碼因?yàn)轭^文件中無(wú)關(guān)的改動(dòng)而被重新編譯多次。

缺點(diǎn)：

前置聲明隱藏了依賴關(guān)系，頭文件改動(dòng)時(shí)，用戶的代碼會(huì)跳過(guò)必要的重新編譯過(guò)程。

前置聲明可能會(huì)被庫(kù)的后續(xù)更改所破壞。前置聲明函數(shù)或模板有時(shí)會(huì)妨礙頭文件開(kāi)發(fā)者變動(dòng)其 API. 例如擴(kuò)大形參類型，加個(gè)自帶默認(rèn)參數(shù)的模板形參等等。

前置聲明來(lái)自命名空間std::的 symbol 時(shí)，其行為未定義。

很難判斷什么時(shí)候該用前置聲明，什么時(shí)候該用#include。極端情況下，用前置聲明代替includes甚至都會(huì)暗暗地改變代碼的含義：

// b.h:struct B {};struct D : B {}// good_user.cc:#include "b.h"void f(B*);void f(void*);void test(D* x) { f(x); } // calls f(B*)

如果#include被B和D的前置聲明替代，test()就會(huì)調(diào)用f(void*).

前置聲明了不少來(lái)自頭文件的 symbol 時(shí)，就會(huì)比單單一行的include冗長(zhǎng)。

僅僅為了能前置聲明而重構(gòu)代碼（比如用指針成員代替對(duì)象成員）會(huì)使代碼變得更慢更復(fù)雜.

結(jié)論：

盡量避免前置聲明那些定義在其他項(xiàng)目中的實(shí)體.

函數(shù)：總是使用#include.

類模板：優(yōu)先使用#include.

至于什么時(shí)候包含頭文件，參見(jiàn)1.5. #include 的路徑及順序。

1.4. 內(nèi)聯(lián)函數(shù)

Tip

只有當(dāng)函數(shù)只有 10 行甚至更少時(shí)才將其定義為內(nèi)聯(lián)函數(shù).

定義:

當(dāng)函數(shù)被聲明為內(nèi)聯(lián)函數(shù)之后, 編譯器會(huì)將其內(nèi)聯(lián)展開(kāi), 而不是按通常的函數(shù)調(diào)用機(jī)制進(jìn)行調(diào)用.

優(yōu)點(diǎn):

只要內(nèi)聯(lián)的函數(shù)體較小, 內(nèi)聯(lián)該函數(shù)可以令目標(biāo)代碼更加高效. 對(duì)于存取函數(shù)以及其它函數(shù)體比較短, 性能關(guān)鍵的函數(shù), 鼓勵(lì)使用內(nèi)聯(lián).

缺點(diǎn):

濫用內(nèi)聯(lián)將導(dǎo)致程序變得更慢. 內(nèi)聯(lián)可能使目標(biāo)代碼量或增或減, 這取決于內(nèi)聯(lián)函數(shù)的大小. 內(nèi)聯(lián)非常短小的存取函數(shù)通常會(huì)減少代碼大小, 但內(nèi)聯(lián)一個(gè)相當(dāng)大的函數(shù)將戲劇性的增加代碼大小. 現(xiàn)代處理器由于更好的利用了指令緩存, 小巧的代碼往往執(zhí)行更快。

結(jié)論:

一個(gè)較為合理的經(jīng)驗(yàn)準(zhǔn)則是, 不要內(nèi)聯(lián)超過(guò) 10 行的函數(shù). 謹(jǐn)慎對(duì)待析構(gòu)函數(shù), 析構(gòu)函數(shù)往往比其表面看起來(lái)要更長(zhǎng), 因?yàn)橛须[含的成員和基類析構(gòu)函數(shù)被調(diào)用!

另一個(gè)實(shí)用的經(jīng)驗(yàn)準(zhǔn)則: 內(nèi)聯(lián)那些包含循環(huán)或switch語(yǔ)句的函數(shù)常常是得不償失 (除非在大多數(shù)情況下, 這些循環(huán)或switch語(yǔ)句從不被執(zhí)行).

有些函數(shù)即使聲明為內(nèi)聯(lián)的也不一定會(huì)被編譯器內(nèi)聯(lián), 這點(diǎn)很重要; 比如虛函數(shù)和遞歸函數(shù)就不會(huì)被正常內(nèi)聯(lián). 通常, 遞歸函數(shù)不應(yīng)該聲明成內(nèi)聯(lián)函數(shù).（YuleFox 注: 遞歸調(diào)用堆棧的展開(kāi)并不像循環(huán)那么簡(jiǎn)單, 比如遞歸層數(shù)在編譯時(shí)可能是未知的, 大多數(shù)編譯器都不支持內(nèi)聯(lián)遞歸函數(shù)). 虛函數(shù)內(nèi)聯(lián)的主要原因則是想把它的函數(shù)體放在類定義內(nèi), 為了圖個(gè)方便, 抑或是當(dāng)作文檔描述其行為, 比如精短的存取函數(shù).

1.5.#include的路徑及順序

Tip

使用標(biāo)準(zhǔn)的頭文件包含順序可增強(qiáng)可讀性, 避免隱藏依賴: 相關(guān)頭文件, C 庫(kù), C++ 庫(kù), 其他庫(kù)的.h, 本項(xiàng)目?jī)?nèi)的.h.

項(xiàng)目?jī)?nèi)頭文件應(yīng)按照項(xiàng)目源代碼目錄樹(shù)結(jié)構(gòu)排列, 避免使用 UNIX 特殊的快捷目錄.(當(dāng)前目錄) 或..(上級(jí)目錄). 例如,google-awesome-project/src/base/logging.h應(yīng)該按如下方式包含:

#include "base/logging.h"

又如,dir/foo.cc或dir/foo_test.cc的主要作用是實(shí)現(xiàn)或測(cè)試dir2/foo2.h的功能,foo.cc中包含頭文件的次序如下:

dir2/foo2.h(優(yōu)先位置, 詳情如下)

C 系統(tǒng)文件

C++ 系統(tǒng)文件

其他庫(kù)的.h文件

本項(xiàng)目?jī)?nèi).h文件

這種優(yōu)先的順序排序保證當(dāng)dir2/foo2.h遺漏某些必要的庫(kù)時(shí)，dir/foo.cc或dir/foo_test.cc的構(gòu)建會(huì)立刻中止。因此這一條規(guī)則保證維護(hù)這些文件的人們首先看到構(gòu)建中止的消息而不是維護(hù)其他包的人們。

dir/foo.cc和dir2/foo2.h通常位于同一目錄下 (如base/basictypes_unittest.cc和base/basictypes.h), 但也可以放在不同目錄下.

按字母順序分別對(duì)每種類型的頭文件進(jìn)行二次排序是不錯(cuò)的主意。注意較老的代碼可不符合這條規(guī)則，要在方便的時(shí)候改正它們。

您所依賴的符號(hào) (symbols) 被哪些頭文件所定義，您就應(yīng)該包含（include）哪些頭文件，前置聲明(forward declarations) 情況除外。比如您要用到bar.h中的某個(gè)符號(hào), 哪怕您所包含的foo.h已經(jīng)包含了bar.h, 也照樣得包含bar.h, 除非foo.h有明確說(shuō)明它會(huì)自動(dòng)向您提供bar.h中的 symbol. 不過(guò)，凡是 cc 文件所對(duì)應(yīng)的「相關(guān)頭文件」已經(jīng)包含的，就不用再重復(fù)包含進(jìn)其 cc 文件里面了，就像foo.cc只包含foo.h就夠了，不用再管后者所包含的其它內(nèi)容。

舉例來(lái)說(shuō),google-awesome-project/src/foo/internal/fooserver.cc的包含次序如下:

#include "foo/public/fooserver.h" // 優(yōu)先位置#include #include #include #include #include "base/basictypes.h"#include "base/commandlineflags.h"#include "foo/public/bar.h"

例外：

有時(shí)，平臺(tái)特定（system-specific）代碼需要條件編譯（conditional includes），這些代碼可以放到其它 includes 之后。當(dāng)然，您的平臺(tái)特定代碼也要夠簡(jiǎn)練且獨(dú)立，比如：

#include "foo/public/fooserver.h"#include "base/port.h" // For LANG_CXX11.#ifdef LANG_CXX11#include #endif // LANG_CXX11

譯者 (YuleFox) 筆記

避免多重包含是學(xué)編程時(shí)最基本的要求;

前置聲明是為了降低編譯依賴，防止修改一個(gè)頭文件引發(fā)多米諾效應(yīng);

內(nèi)聯(lián)函數(shù)的合理使用可提高代碼執(zhí)行效率;

-inl.h可提高代碼可讀性 (一般用不到吧:D);

標(biāo)準(zhǔn)化函數(shù)參數(shù)順序可以提高可讀性和易維護(hù)性 (對(duì)函數(shù)參數(shù)的堆?？臻g有輕微影響, 我以前大多是相同類型放在一起);

包含文件的名稱使用.和..雖然方便卻易混亂, 使用比較完整的項(xiàng)目路徑看上去很清晰, 很條理, 包含文件的次序除了美觀之外, 最重要的是可以減少隱藏依賴, 使每個(gè)頭文件在 “最需要編譯” (對(duì)應(yīng)源文件處 :D) 的地方編譯, 有人提出庫(kù)文件放在最后, 這樣出錯(cuò)先是項(xiàng)目?jī)?nèi)的文件, 頭文件都放在對(duì)應(yīng)源文件的最前面, 這一點(diǎn)足以保證內(nèi)部錯(cuò)誤的及時(shí)發(fā)現(xiàn)了.

譯者（acgtyrant）筆記

原來(lái)還真有項(xiàng)目用#includes來(lái)插入文本，且其文件擴(kuò)展名.inc看上去也很科學(xué)。

Google 已經(jīng)不再提倡-inl.h用法。

注意，前置聲明的類是不完全類型（incomplete type），我們只能定義指向該類型的指針或引用，或者聲明（但不能定義）以不完全類型作為參數(shù)或者返回類型的函數(shù)。畢竟編譯器不知道不完全類型的定義，我們不能創(chuàng)建其類的任何對(duì)象，也不能聲明成類內(nèi)部的數(shù)據(jù)成員。

類內(nèi)部的函數(shù)一般會(huì)自動(dòng)內(nèi)聯(lián)。所以某函數(shù)一旦不需要內(nèi)聯(lián)，其定義就不要再放在頭文件里，而是放到對(duì)應(yīng)的.cc文件里。這樣可以保持頭文件的類相當(dāng)精煉，也很好地貫徹了聲明與定義分離的原則。

在#include中插入空行以分割相關(guān)頭文件, C 庫(kù), C++ 庫(kù), 其他庫(kù)的.h和本項(xiàng)目?jī)?nèi)的.h是個(gè)好習(xí)慣。