├── .gitignore ├── src ├── work-in-progress.md ├── scoping │ ├── README.md │ ├── internal-linkage.md │ ├── nonmember-static-members.md │ ├── local-variables.md │ ├── thread-local-variables.md │ ├── static-and-global-variables.md │ └── namespaces.md ├── other-cpp-features │ ├── README.md │ ├── alias.md │ ├── exceptions.md │ ├── preprocessor-marcos.md │ └── template-metaprogramming.md ├── naming │ ├── concept-names.md │ ├── aliases.md │ ├── template-parameter-names.md │ ├── macro-names.md │ ├── README.md │ ├── exceptions-to-naming-rules.md │ ├── function-names.md │ ├── namespace-names.md │ ├── type-names.md │ ├── enumerator-names.md │ ├── file-names.md │ ├── constant-names.md │ ├── variable-names.md │ └── choosing-names.md ├── classes │ ├── README.md │ ├── struct-vs-paris-and-tuples.md │ ├── structs-vs-classes.md │ ├── doing-work-in-constructor.md │ ├── implicit-conversions.md │ └── copyable-and-movable-types.md ├── cpp-version.md ├── header-files │ ├── README.md │ ├── define-guard.md │ ├── include-what-you-use.md │ ├── inline-functions.md │ ├── forward-declarations.md │ ├── self-contained-headers.md │ └── names-and-order-of-includes.md ├── background │ ├── README.md │ └── goals-of-the-style-guide.md ├── README.md ├── SUMMARY.md └── english-word-table.md ├── book.toml ├── theme └── head.hbs ├── .github └── workflows │ └── deploy.yaml └── README.md /.gitignore: -------------------------------------------------------------------------------- 1 | book 2 | -------------------------------------------------------------------------------- /src/work-in-progress.md: -------------------------------------------------------------------------------- 1 | # 建置中... -------------------------------------------------------------------------------- /src/scoping/README.md: -------------------------------------------------------------------------------- 1 | # 作用域 (Scoping) 2 | -------------------------------------------------------------------------------- /src/other-cpp-features/README.md: -------------------------------------------------------------------------------- 1 | # 🚧 其他 C++ 特性 2 | -------------------------------------------------------------------------------- /src/other-cpp-features/alias.md: -------------------------------------------------------------------------------- 1 | ## 🚧 別名 (Alias) 2 | 3 | WIP 4 | -------------------------------------------------------------------------------- /src/other-cpp-features/exceptions.md: -------------------------------------------------------------------------------- 1 | ## 🚧 例外 (Exceptions) 2 | 3 | WIP 4 | -------------------------------------------------------------------------------- /src/other-cpp-features/preprocessor-marcos.md: -------------------------------------------------------------------------------- 1 | ## 🚧 預處理器巨集 2 | 3 | WIP 4 | -------------------------------------------------------------------------------- /src/naming/concept-names.md: -------------------------------------------------------------------------------- 1 | ## 概念名稱 (Concept Names) 2 | 3 | > 概念名稱使用與 [型別名稱](type-names.md) 相同的規則。 4 | -------------------------------------------------------------------------------- /src/classes/README.md: -------------------------------------------------------------------------------- 1 | # 類別 (Classes) 2 | 3 | 類別是 C++ 程式碼中的基本元件。 我們很自然地會廣泛使用它。 這章列出了你在撰寫類別的時候，應該以及不應該做的事情。 -------------------------------------------------------------------------------- /src/other-cpp-features/template-metaprogramming.md: -------------------------------------------------------------------------------- 1 | ## 🚧 模板元程式設計 (Template Metaprogramming) 2 | 3 | WIP 4 | -------------------------------------------------------------------------------- /src/naming/aliases.md: -------------------------------------------------------------------------------- 1 | ## 別名 (Aliases) 2 | 3 | > [別名](../other-cpp-features/alias.md) 的名稱遵循與其他新名稱相同的原則，命名方式是根據別名被定義的上下文來決定，而不是根據原始名稱出現的位置。 4 | -------------------------------------------------------------------------------- /src/naming/template-parameter-names.md: -------------------------------------------------------------------------------- 1 | ## 模板參數名稱 (Template Parameter Names) 2 | 3 | > 模板參數應該依據他所屬的類別來決定命名風格： 型別模板參數應該遵循[型別](./type-names.md)的命名規則，然後非型別模板參數應該遵循[變數](./variable-names.md)或[常數](./constant-names.md)的命名規則。 4 | -------------------------------------------------------------------------------- /book.toml: -------------------------------------------------------------------------------- 1 | [book] 2 | authors = ["SLMT"] 3 | multilingual = false 4 | src = "src" 5 | title = "Google C++ Style Guide 繁體中文版" 6 | 7 | [output.html] 8 | no-section-label = true 9 | 10 | [output.html.fold] 11 | enable = true 12 | -------------------------------------------------------------------------------- /src/cpp-version.md: -------------------------------------------------------------------------------- 1 | # C++ 版本 2 | 3 | 目前程式碼應以 C++20 版為目標，這也代表不應該使用 C++23 的特性。 本指南作為目標的 C++ 版本會隨時間快速更新。 4 | 5 | 不要使用非標準的擴充功能 (Non-standard Extensions) (TODO: 加入到該章節的連結)。 6 | 7 | 在你的專案使用 C++17 與 C++20 的特性以前應考慮不同環境的可攜性 (Portability)。 8 | -------------------------------------------------------------------------------- /src/header-files/README.md: -------------------------------------------------------------------------------- 1 | # 標頭檔 (Header Files) 2 | 3 | 一般來說，每一個 `.cc` 檔都應該要有一個對應的 `.h` 檔。 不過也有一些常見的例外，像是單元測試 (Unit Test) 跟一些只包含著 `main()` 的小型 `.cc` 檔就不需要有。 4 | 5 | 正確地使用標頭檔可以對可讀性、程式碼大小與效能帶來巨大的影響。 6 | 7 | 本章中的規則會引領你克服標頭檔中各式各樣的陷阱。 8 | -------------------------------------------------------------------------------- /src/naming/macro-names.md: -------------------------------------------------------------------------------- 1 | ## 巨集名稱 (Macro Names) 2 | 3 | > 你不是真要定義一個[巨集](../other-cpp-features/preprocessor-marcos.md)吧？ 如果真的要做的話，他們應該長這樣：`MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE`。 4 | 5 | 請先閱讀[關於巨集的說明](../other-cpp-features/preprocessor-marcos.md)； 一般來說不該使用巨集。 然而如果你真的需要使用，他們應該全部使用大寫與底線命名，並同時以專案名稱作為開頭。 6 | 7 | ```cpp 8 | #define MYPROJECT_ROUND(x) ... 9 | ``` 10 | -------------------------------------------------------------------------------- /src/classes/struct-vs-paris-and-tuples.md: -------------------------------------------------------------------------------- 1 | ## 結構 (Struct) 與對 (Pair) 和元組 (Tuple) 的比較 2 | 3 | > 當元素可以有明確的名稱時，偏好使用 `struct` 而非對 (pair) 與元組 (tuple)。 4 | 5 | 雖然使用對與元組可以避免定義自訂型別，並可能減少需要撰寫的程式碼，但是欄位名稱總比 `.first`、`.second` 或 `std::get` 清楚好讀。 雖然 C++14 後來引進了 `std::get` 來透過型別來存取，而不是透過索引存取元組的元件，這在某些情況下能部分減輕問題，但是欄位名稱還是比型別名稱更清楚且更具資訊。 6 | 7 | 在泛型程式碼中，如果元素本身沒有特定意義時，對和元組可能是適合的選擇。 他們也可以用在既有的程式碼或 API 有要求時。 8 | -------------------------------------------------------------------------------- /src/header-files/define-guard.md: -------------------------------------------------------------------------------- 1 | ## `#define` 保護 (The `#define` Guard) 2 | 3 | > 所有的標頭檔應該要包含 `#define` 保護，以防止多重載入。 其名稱的格式為 `<專案名稱>_<路徑>_<檔名>_H_`。 4 | 5 | 為了保證名稱的獨特性，應該要遵照該檔案在專案中的完整路徑來定義。 例如，一個在專案 foo 之中 `foo/src/bar/baz.h` 位置下的檔案，其保護應該要這樣寫： 6 | 7 | ```c++ 8 | #ifndef FOO_BAR_BAZ_H_ 9 | #define FOO_BAR_BAZ_H_ 10 | 11 | ... 12 | 13 | #endif // FOO_BAR_BAZ_H_ 14 | ``` -------------------------------------------------------------------------------- /src/naming/README.md: -------------------------------------------------------------------------------- 1 | # 命名 (Naming) 2 | 3 | 最重要的一致性規則是那些規範命名方式的規則。 一個名稱的風格能夠立即告訴我們被命名的實體是哪種類型，而不需要去搜尋該實體的宣告：一個型別、一個變數、一個函數、一個常數、一個巨集等等。 我們大腦中的模式匹配 (Pattern-Matching) 引擎高度仰賴這些命名規則。 4 | 5 | 命名的規則相當主觀，但我們認為在這個領域內，一致性比個人喜好更重要。 因此無論你認為這些規則是否合理，規則就是規則。 6 | 7 | 對於以下的命名規則來說，在這裡所謂的『單字』，指的是以英文撰寫、不含空格的詞彙。 無論這些單字是全部都小寫，中間包含底線（蛇形命名法：`snake_case`），或者是由多個單字組成，且每個單字的首字母大寫的寫法（駝峰式命名法：`camelCase` 或帕斯卡命名法：`PascalCase`）。 8 | -------------------------------------------------------------------------------- /src/naming/exceptions-to-naming-rules.md: -------------------------------------------------------------------------------- 1 | ## 名稱規則的例外 (Exceptions to Naming Rules) 2 | 3 | > 如果你正在為類似於 C 或 C++ 內已經存在的實體進行命名，那麼你可以遵循既有的命名慣例。 4 | 5 | - `bigopen()` 6 | - 函式名稱，依循 `open()` 的命名風格。 7 | - `uint` 8 | - `typedef` 9 | - `bigpos` 10 | - `struct` 或 `class` 名稱，依循 `pos` 的命名方式。 11 | - `sparse_hash_map` 12 | - 類 STL 的實體；遵循 STL 的命名慣例。 13 | - `LONGLONG_MAX` 14 | - 常數名稱，類似 `INT_MAX` 的命名方式。 15 | -------------------------------------------------------------------------------- /theme/head.hbs: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /src/background/README.md: -------------------------------------------------------------------------------- 1 | # 背景 2 | 3 | C++ 是許多 Google 開源專案中主要使用的程式語言之一。 如同許多 C++ 程式設計師所知，C++ 具有許多強大的特性，但這種強大也帶來了複雜性，使得程式碼容易產生各種錯誤 (Bug)，並且也難以閱讀及維護。 4 | 5 | 本指南的目標在於藉由詳細說明哪些東西該寫、哪些不該寫，來管理 C++ 程式碼的複雜度。 這些規則存在的目的即是讓程式碼保持易於維護的同時，也讓開發者能有效地發揮 C++ 的特性。 6 | 7 | 風格 (Style)，也稱作可讀性 (Readability)，即是我們用來管理 C++ 程式碼中遵循的慣例。 事實上，用 Style 這個字眼可能不太精確，因為這類約定並非只有著墨在程式碼的排版。 8 | 9 | Google 開發的絕大多數開源專案都遵循本指南。 10 | 11 | 請注意：本指南並非 C++ 教學，我們假設讀者已熟悉這門程式語言。 12 | -------------------------------------------------------------------------------- /src/naming/function-names.md: -------------------------------------------------------------------------------- 1 | ## 函數名稱 (Function Names) 2 | 3 | > 一般函式應使用大小寫混合命名法 (mixed case)；而存取子 (Accessor) 與修改子 (Mutator) 則可以選擇以變數風格命名。 4 | 5 | 一般來說，函式應以大寫字母開頭，並在每一個新單字的首字使用大寫字母。 6 | 7 | ```c++ 8 | AddTableEntry() 9 | DeleteUrl() 10 | OpenFileOrDie() 11 | ``` 12 | 13 | (相同的命名規則也適用於類別與名稱空間範圍之中，那些作為 API 的一部分公開的、或是意圖讓其看起來像函數的常數。 因為它們是物件而非函式這一點只是無關緊要的實作細節。) 14 | 15 | 存取子與修改子 (get 與 set 函式) 可以用變數的方式命名，這些函式的命名通常對應到實際的成員變數，但這並非必要。 例如：`int count()` 與 `void set_count(int count)`。 16 | -------------------------------------------------------------------------------- /src/scoping/internal-linkage.md: -------------------------------------------------------------------------------- 1 | ## 內部鏈結 (Internal Linkage) 2 | 3 | > 當 `.cc` 檔中的定義不需要被外部檔案參考時，請透過將其放入無名名稱空間或宣告為 `static` 來使其具有內部鏈結，但不要在 `.h` 檔內使用任何這種結構。 4 | 5 | ### 定義 6 | 7 | 所有的宣告都可以透過放入無名名稱空間來使其具有內部鏈結。 函數與變數也可以透過宣告為 `static` 來實現內部鏈結。 這表示所宣告的內容無法被其他檔案存取。 如果其他檔案中宣告了同樣名稱的東西，那麼這兩者會被視為獨立的個體。 8 | 9 | ### 決定 10 | 11 | 我們鼓勵在 `.cc` 檔中對不需要外部引用的程式碼使用內部鏈結，但不要在 `.h` 檔中使用。 12 | 13 | 無名名稱空間的格式與具名名稱空間相同。 對於這種名稱空間的結尾註解，只要在名稱的部分留白即可： 14 | 15 | ```c++ 16 | namespace { 17 | ... 18 | } // namespace 19 | ``` 20 | -------------------------------------------------------------------------------- /src/naming/namespace-names.md: -------------------------------------------------------------------------------- 1 | ## 名稱空間名稱 (Namespace Names) 2 | 3 | > 名稱空間應使用蛇形命名法 (`snake_case`，全部小寫，並且用底線分開單字)。 4 | 5 | 在為名稱空間[選擇名稱](./choosing-names.md)的時候，應該注意在名稱空間外的標頭檔就必須使用完整限定名稱 (fully qualified name)，因為[未限定名稱的別名一般來說不被允許](../other-cpp-features/alias.md)。 6 | 7 | 頂層的名稱空間應該要在全域之中獨一無二而且容易辨識，而且應該由一個專案或團隊擁有，其中命名應基於該專案或團隊的名稱。 通常所有該名稱空間下的程式碼應該都要在與名稱空間名字相同的一個或多個資料夾內。 8 | 9 | 巢狀名稱空間 (nested namespaces) 應該避免使用已知的頂層名稱，特別是 `std` 或 `absl`，因為在 C++ 中，名稱空間不會防範其他名稱空間下的命名衝突 (請參考 [TotW #130](https://abseil.io/tips/130))。 10 | -------------------------------------------------------------------------------- /src/naming/type-names.md: -------------------------------------------------------------------------------- 1 | ## 型別名稱 (Type Names) 2 | 3 | > 型別名稱始於一個大寫字母，並且每個單字的開頭皆為大寫字母，同時不包含底線：`MyExcitingClass`、`MyExcitingEnum`。 4 | 5 | 所有型別的名稱 - 類別、結構、型別別名、列舉、型別模板參數 - 都有相同的命名慣例。 型別名稱始於一個大寫字母，並且每個單字的開頭皆為大寫字母。 沒有底線。 例如： 6 | 7 | ```c++ 8 | // 類別與結構 9 | class UrlTable { ... 10 | class UrlTableTester { ... 11 | struct UrlTableProperties { ... 12 | 13 | // typedef 14 | typedef hash_map PropertiesMap; 15 | 16 | // 使用別名 17 | using PropertiesMap = hash_map; 18 | 19 | // 列舉 20 | enum UrlTableErrors { ... 21 | ``` 22 | -------------------------------------------------------------------------------- /src/scoping/nonmember-static-members.md: -------------------------------------------------------------------------------- 1 | ## 非成員、靜態成員、全域函式 2 | 3 | > 盡量將非成員函式放在名稱空間中；應盡量避免使用全域範圍的函式（即不屬於任何名稱空間的函式）。 請不要單純為了組合靜態函式而創建一個類別。 類別的靜態函式一般來說應該要與類別的實例或者靜態資料有高度相關。 4 | 5 | ### 優點 6 | 7 | 非成員及靜態成員函式在某些狀況下很有用。 將非成員函式放在名稱空間中可以避免汙染全域的名稱空間。 8 | 9 | ### 缺點 10 | 11 | 非成員及靜態成員函式也許作為某個類別中的成員會更合理，特別是當它們需要存取外部資源或具有較高的相依性時。 12 | 13 | ### 決定 14 | 15 | 有時候定義一個不受類別實例綁住的函式很有用。 這樣的函式可以是靜態成員或者非成員函式。 非成員函式不應該依賴在某個外部變數上，而且應該幾乎都放在某個名稱空間內。 不要為了將一組靜態成員歸類而建立類別，這與直接在函式名稱前加上相同前綴並無不同，而這種做法通常沒有必要。 16 | 17 | 如果你定義了一個非成員函式，而且它只需要用在它所屬的 `.cc` 檔中，請使用 [內部鏈結](internal-linkage.md) 來限制它的作用域。 18 | -------------------------------------------------------------------------------- /src/naming/enumerator-names.md: -------------------------------------------------------------------------------- 1 | ## 列舉器名稱 (Enumerator Names) 2 | 3 | > 列舉器的值 (無論是否有限定作用域) 都應該要以[常數](constant-names.md)方式命名，不可以用[巨集](macro-names.md)的方式；也就是像是 `kEnumName` ，不可以像是 `ENUM_NAME`。 4 | 5 | 範例： 6 | 7 | ```cpp 8 | enum class UrlTableError { 9 | kOk = 0, 10 | kOutOfMemory, 11 | kMalformedInput, 12 | }; 13 | ``` 14 | 15 | 不好的例子： 16 | 17 | ```cpp 18 | enum class AlternateUrlTableError { 19 | OK = 0, 20 | OUT_OF_MEMORY = 1, 21 | MALFORMED_INPUT = 2, 22 | }; 23 | ``` 24 | 25 | 到 2009 年一月前，這個指引寫著應該要以[巨集](macro-names.md)的方式命名。 這導致列舉值與巨集名稱之間產生衝突。 因此才改成了建議使用常數命名法。 新的程式碼應該皆使用常數命名法。 26 | -------------------------------------------------------------------------------- /.github/workflows/deploy.yaml: -------------------------------------------------------------------------------- 1 | name: Deploy 2 | on: 3 | push: 4 | branches: 5 | - master 6 | jobs: 7 | deploy: 8 | runs-on: ubuntu-latest 9 | steps: 10 | - name: Checkout 🛎️ 11 | uses: actions/checkout@v4 12 | 13 | - name: Setup mdbook 🦀 14 | uses: peaceiris/actions-mdbook@v2 15 | with: 16 | mdbook-version: '0.4.45' 17 | 18 | - name: Build 📕 19 | run: mdbook build 20 | 21 | - name: Deploy 🚀 22 | uses: JamesIves/github-pages-deploy-action@v4.6.1 23 | with: 24 | branch: gh-pages 25 | folder: book -------------------------------------------------------------------------------- /src/naming/file-names.md: -------------------------------------------------------------------------------- 1 | ## 檔案名稱 (File Names) 2 | 3 | > 檔案名稱應該全部使用小寫字母，並可以包含底線 (`_`) 或是橫槓 (`-`)。 關於這點請遵循各專案的慣例。 如果沒有一致可循的本地慣例，偏好使用 `_`。 4 | 5 | 一些可接受的檔案名稱範例： 6 | 7 | - `my_useful_class.cc` 8 | - `my-useful-class.cc` 9 | - `myusefulclass.cc` 10 | - `myusefulclass_test.cc // _unittest 與 _regtest 這兩種寫法已經不再推薦使用` 11 | 12 | C++ 檔案應該以 `.cc` 結尾，同時標頭檔應該以 `.h` 結尾。 需要在某個特定位置以文字方式引入的檔案應該以 `.inc` 結尾 (更多請看[自給自足標頭檔](../header-files/self-contained-headers.md)的章節)。 13 | 14 | 不要使用已經存在於 `/usr/include` 的檔名，像是 `db.h`。 15 | 16 | 一般來說，應該要讓你的檔案名稱非常精確。 例如，使用 `http_server_logs.h` 而不是 `logs.h`。 一個常見的情況是，當定義名為 `FooBar` 的類別時，通常會有一對檔案分別名為 `foo_bar.h` 與 `foo_bar.cc`。 17 | -------------------------------------------------------------------------------- /src/classes/structs-vs-classes.md: -------------------------------------------------------------------------------- 1 | ## 結構 (struct) 與 類別 (class) 的比較 2 | 3 | > 只對僅用於承載資料的被動物件使用 `struct`，剩下的都用 `class`。 4 | 5 | C++ 中的 `struct` 與 `class` 幾乎相同，不過我們對這些關鍵字賦予了額外的語義，因此你應該要注意對你定義的資料型別賦予適當的關鍵字。 6 | 7 | `struct` 應該被用在那些攜帶資料，也可以包含相關常數的被動性物件。 所有的欄位必須是公用的 (`public`)。 `struct` 不該包含暗示不同欄位之間關係的不變條件 (invariant)，因為直接存取那些欄位可能會打破那些不變條件。 建構函式、解構函式與幫手函式可以存在；但這些函式不該要求或強制任何不變條件。 8 | 9 | 如果需要更多的功能或不變條件，抑或是 `struct` 具有廣泛可見度並且預期會持續演化，那麼使用 `class` 應該更為恰當。 如果有疑慮，就用 `class`。 10 | 11 | 為了與 STL 保持一致性，你可以對不保存狀態的型別，像是特徵 (trait)、[模板元函式 (template metafunctions)](../other-cpp-features/template-metaprogramming.md) 與一些函子 (functor) 使用 `struct`。 12 | 13 | 注意 `struct` 與 `class` 的成員變數有著[不同的命名規則](../naming/variable-names.md)。 14 | -------------------------------------------------------------------------------- /src/classes/doing-work-in-constructor.md: -------------------------------------------------------------------------------- 1 | ## 在建構函式內的工作 2 | 3 | > 避免在建構函式內呼叫虛擬函式，並且在無法適當回報錯誤時，避免進行可能失敗的初始化。 4 | 5 | ### 定義 6 | 7 | 建構函式內可以執行任意的初始化動作。 8 | 9 | ### 優點 10 | 11 | - 不需要擔心類別是否已經初始化過了。 12 | - 已經經過建構函式充分初始化的物件可以作為 `const` 使用，而且與標準容器與演算法使用時更容易。 13 | 14 | ### 缺點 15 | 16 | - 如果在建構函式內呼叫虛擬函式，這些呼叫不會被轉發至子類別的實作。 即使你的類別目前沒有子類別，未來的修改可能會悄然引入這個問題，造成困惑。 17 | - 建構函式沒有簡單的方法來回報錯誤，除了直接讓程式崩潰 (這並不總是合適) 或使用例外 (也被我們 [禁止](../other-cpp-features/exceptions.md) 了)。 18 | - 如果工作失敗了，那我們此時就會有個初始化失敗的物件。 這時可能需要提供 `bool IsValid()` 之類的方法來檢查狀態，但這種機制容易被遺漏，導致錯誤。 19 | - 由於無法取得建構函式的函式指標，因此建構函式內的工作難以被移交，例如交給另一個執行緒。 20 | 21 | ### 決定 22 | 23 | 建構函式應該永遠不要呼叫虛擬函式。 在適當的情況下，終止程式可能是一種合理的錯誤處理方式。 否則，可以考慮像 [TotW #42](https://abseil.io/tips/42) 所述那樣建立工廠方法 (Factory Method) 或者 `Init()` 方法。 避免在沒有其他狀態影響可呼叫公用方法的物件上使用 `Init()` 方法 (這類半建構狀態的物件特別難以正確使用) (譯註：這句話的意思是，如果沒有需要延遲初始化或者錯誤處理的需求，就不要特別為了初始化寫一個 `Init()`，而是使用建構函式進行初始化即可。) 24 | -------------------------------------------------------------------------------- /src/header-files/include-what-you-use.md: -------------------------------------------------------------------------------- 1 | ## 引入你需要的 2 | 3 | > 如果一份原始碼檔或者標頭檔使用了一個定義在其他地方的符號，該檔應該要直接引入明確提供該符號的宣告或者定義的標頭檔。 它不應該為了其他目的引入標頭檔。 4 | 5 | 不要依賴傳遞式引入 (Transitive Inclusions) (譯註二)。 這讓大家可以放心移除自己標頭檔中不需要的 `#include`，而不會影響使用該標頭檔案的程式碼。 這項原則同樣適用於相關標頭檔： `foo.cc` 如果使用了 `bar.h` 的符號，那就該直接引入。 即使 `foo.h` 已經引入了 `bar.h`，`foo.cc` 仍應直接引入 `bar.h`。 6 | 7 | #### 譯註二：傳遞式引入 (Transitive Inclusion) 說明 8 | 9 | 假設有以下兩個標頭檔： 10 | 11 | `a_class.h`: 12 | 13 | ```cpp 14 | #ifndef A_CLASS_H 15 | #define A_CLASS_H 16 | 17 | class A { 18 | public: 19 | void DoSomethingA(); 20 | }; 21 | 22 | #endif // A_CLASS_H 23 | ``` 24 | 25 | `b_class.h`: 26 | 27 | ```cpp 28 | #ifndef B_CLASS_H 29 | #define B_CLASS_H 30 | 31 | #include "a_class.h" 32 | 33 | class B { 34 | public: 35 | void DoSomethingB(A a); 36 | }; 37 | 38 | #endif // B_CLASS_H 39 | ``` 40 | 41 | 此時若 `class B` 的實作 `b_class.cc` 沒有引入 `a_class.h`，而是依賴 `b_class.h` 的引入的話，就叫做傳遞式引入。 但 Google 的風格指南是鼓勵不要依賴這種引入。 42 | -------------------------------------------------------------------------------- /src/naming/constant-names.md: -------------------------------------------------------------------------------- 1 | ## 常數名稱 2 | 3 | > 使用 `constexpr` 或 `const` 宣告的變數，以及數值在整個程式執行期間皆固定的變數，其名稱應該以「k」為開頭，並使用大小寫混和命名法 (mixed case)。 僅在無法用大小寫分隔的少數特殊情況下，才可使用底線分隔。例如： 4 | > ```cpp 5 | > const int kDaysInAWeek = 7; 6 | > const int kAndroid8_0_0 = 24; // Android 8.0.0 7 | > ``` 8 | > 所有具備以上性質同時有靜態儲存期 (例如靜態變數與全域變數，詳情請參照[儲存期](http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration)) 的變數都應該這樣命名，包括類別中的靜態常數資料成員以及在模板中可能因不同實例而有不同值的成員。 對於其他儲存類別的變數而言，此命名慣例屬於選擇性的 (例如自動變數)，其他情況應使用一般的變數命名規則，例如： 9 | > ```cpp 10 | > void ComputeFoo(absl::string_view suffix) { 11 | > // 任何一種寫法都可以接受 12 | > const absl::string_view kPrefix = "prefix"; 13 | > const absl::string_view prefix = "prefix"; 14 | > ... 15 | >} 16 | > ``` 17 | > 不好的例子： 18 | > ```cpp 19 | > void ComputeFoo(absl::string_view suffix) { 20 | > // 不好 - 每次呼叫 `ComputeFoo` 時可能都會產生不同的 `kCombined` 數值 21 | > const std::string kCombined = absl::StrCat(kPrefix, suffix); 22 | > ... 23 | >} 24 | >``` -------------------------------------------------------------------------------- /src/header-files/inline-functions.md: -------------------------------------------------------------------------------- 1 | ## 行內函式 (Inline Functions) 2 | 3 | > 當函式程式碼較少 (少於或等於 10 行時)，可以考慮將它宣告為行內函式。 4 | 5 | ### 定義 6 | 7 | 透過宣告函式為行內函式，可以讓編譯器直接在呼叫該函式的地方展開函式，而不是遵照一般的函式呼叫機制。 8 | 9 | ### 優點 10 | 11 | 若函式足夠小，行內化可以幫助產生更有效率的目的碼 (object code)。 你可以盡量將存取函式 (accessor) 、修改函式 (mutator) 以及一些極短但對效能有巨大影響的函式行內化。 12 | 13 | ### 缺點 14 | 15 | 過度使用行內函式可能會造成程式變慢。 依照函式長度的不同，行內化可能會增加或減少程式碼的大小。 行內化一個很小的存取函式通常可以縮小程式碼體積，而行內化一個較大的函式則可能會大幅增加程式碼的大小。 現代的處理器因為可以更有效率地使用指令快取 (instruction cache)，處理較短的程式碼通常會更快。 16 | 17 | ### 決定 18 | 19 | 一個適當的規則是不要將 10 行以上的函式行內化。 需要特別注意解構函式 (destructors)，它們往往比表面上看到的更長，因為還包含了隱含的基底類別 (base class) 與成員解構函式的呼叫。 20 | 21 | 另一個有用的規則： 一般來說將一個具有迴圈或者 `switch` 的函式行內化 (除非大多數的情況下這個迴圈或 `switch` 都不會被執行)，通常不是有效率的做法。 22 | 23 | 還有一個重要的須知：就算將一個函式宣告為行內函式，編譯器也不一定會照做。 例如：虛擬函式 (virtual function) 或遞迴函式 (recursive function) 一般不會被行內化。 遞迴函式通常不應該行內化。 至於將虛擬函式寫成行內函式的理由，通常只是為了方便將函式的定義放在類別內，或是用來記錄其行為，例如存取函式與修改函式。 24 | 25 | ### 譯註三：行內函式範例 26 | 27 | 這邊提供一個行內函式的範例，主要是透過 `inline` 關鍵字將函式行內化： 28 | 29 | ```c++ 30 | inline int sum(int a, int b) { 31 | return a + b; 32 | } 33 | ``` 34 | -------------------------------------------------------------------------------- /src/naming/variable-names.md: -------------------------------------------------------------------------------- 1 | ## 變數名稱 (Variable Names) 2 | 3 | > 變數 (包含函式的參數) 與資料成員的名稱都用蛇形命名法（`snake_case`，也就是全部小寫，並使用底線隔開單字）。 類別的資料成員（但結構的資料成員不包括在內）還需在名稱尾端加上底線。 例如，區域變數：`a_local_variable`、結構資料成員：`a_struct_data_member`、類別資料成員：`a_class_data_member_`。 4 | 5 | ### 一般變數名稱 6 | 7 | 好的： 8 | 9 | ```cpp 10 | string table_name; // 可以 - 蛇形命名法 11 | ``` 12 | 13 | 不好的： 14 | 15 | ```cpp 16 | string tableName; // 不好 - 大小寫混合 17 | ``` 18 | 19 | ### 類別資料成員 20 | 21 | 類別的資料成員（無論是靜態或非靜態）應像一般的非成員變數一樣命名，但要加上尾端底線。 唯一的例外是靜態常數類別成員，應該要以 [常數的方式](constant-names.md) 命名。 22 | 23 | ```cpp 24 | class TableInfo { 25 | public: 26 | ... 27 | static const int kTableVersion = 3; // 可以 - 常數命名方式 28 | ... 29 | 30 | private: 31 | std::string table_name_; // 可以 - 尾端有底線 32 | static Pool* pool_; // 可以 33 | }; 34 | ``` 35 | 36 | ### 結構資料成員 37 | 38 | 結構的資料成員（無論是靜態或非靜態）應像一般的非成員變數一樣命名。 不像類別的資料成員，它們不需加上尾端底線。 39 | 40 | ```cpp 41 | struct UrlTableProperties { 42 | std::string name; 43 | int num_entries; 44 | static Pool* pool; 45 | }; 46 | ``` 47 | 48 | 請參考 [結構與類別章節](../classes/structs-vs-classes.md) 的討論來瞭解何時該使用結構而不是類別。 49 | -------------------------------------------------------------------------------- /src/scoping/local-variables.md: -------------------------------------------------------------------------------- 1 | ## 區域變數 2 | 3 | > 將函式的變數盡可能地放在最小的作用域內，並在宣告變數的同時初始化。 4 | 5 | C++ 允許你在函式內的任何地方宣告變數。 我們鼓勵你盡可能地將變數宣告在越局部的作用域越好，並且最好靠近它第一次被使用的地方。 這讓讀者更容易找到變數的宣告位置，並了解其型別及初始化值。 特別要注意初始化與宣告應避免分開，例如： 6 | 7 | ```cpp 8 | int i; 9 | i = f(); // 不好 -- 初始化與宣告分離 10 | ``` 11 | 12 | ```cpp 13 | int i = f(); // 很好 -- 宣告同時初始化 14 | ``` 15 | 16 | ```cpp 17 | int jobs = NumJobs(); 18 | // 很多程式碼... 19 | f(jobs); // 不好 -- 宣告與使用處分離 20 | ``` 21 | 22 | ```cpp 23 | int jobs = NumJobs(); 24 | f(jobs); // 很好 -- 宣告後面緊跟著（或很接近）使用處 25 | ``` 26 | 27 | ```cpp 28 | std::vector v; 29 | v.push_back(1); // 偏好使用大括號初始化法 (brace initialization) 30 | v.push_back(2); 31 | ``` 32 | 33 | ```cpp 34 | std::vector v = {1, 2}; // 很好 -- v 一開始就初始化好 35 | ``` 36 | 37 | `if`、`while` 與 `for` 陳述句需要的變數一般來說應宣告在該陳述句內，以將其限制在對應的作用域中。 例如： 38 | 39 | ```cpp 40 | while (const char* p = strchr(str, '/')) str = p + 1; 41 | ``` 42 | 43 | 有一個例外：如果該變數是物件，則每次進入該作用域時，建構函式都會被呼叫，而解構函式則會在離開時執行。 44 | 45 | ```cpp 46 | // 低效率的寫法 47 | for (int i = 0; i < 1000000; ++i) { 48 | Foo f; // 我的建構函式與解構函式會各被呼叫 1000000 次 49 | f.DoSomething(i); 50 | } 51 | ``` 52 | 53 | 在這種情況下，將變數宣告在迴圈外能提升執行效率： 54 | 55 | ```cpp 56 | Foo f; // 我的建構函式與解構函式只會各被呼叫一次 57 | for (int i = 0; i < 1000000; ++i) { 58 | f.DoSomething(i); 59 | } 60 | ``` 61 | -------------------------------------------------------------------------------- /src/header-files/forward-declarations.md: -------------------------------------------------------------------------------- 1 | ## 前向宣告 (Forward Declarations) 2 | 3 | > 盡可能地避免使用前向宣告。 [只要 `#include` 你需要的標頭檔就好](./include-what-you-use.md)。 4 | 5 | ### 定義 6 | 7 | 前向宣告是指在沒有提供完整定義的情況下，預先宣告某個實體的存在： 8 | 9 | ```cpp 10 | // 在 C++ 程式碼中： 11 | class B; 12 | void FuncInB(); 13 | extern int variable_in_b; 14 | ABSL_DECLARE_FLAG(flag_in_b); // 譯註：這是 Abseil 函式庫中一個用於宣告旗標（flag）的巨集。 15 | ``` 16 | 17 | ### 優點 18 | 19 | - 前向宣告可以節省編譯時間。 `#include` 會迫使編譯器開啟更多檔案與處理更多輸入。 20 | - 前向宣告可以避免不必要的重編譯。 `#include` 在標頭檔做了一些無關的改動時，也會迫使編譯器重新編譯你的程式碼。 21 | 22 | ### 缺點 23 | 24 | - 前向宣告會隱藏依賴，這會讓使用者的程式碼在標頭檔被修改後略過了可能必要的重新編譯過程。 25 | - 前向宣告相較於 `#include` 會讓自動化工具更難找出定義一個符號的模組為何。 26 | - 一個前向宣告可能會被函式庫後續的修改搞壞。 函式與模板的前向宣告可能會限制標頭檔維護者對 API 進行變更，例如擴大參數型別、為模板新增預設參數，或遷移至新的命名空間。 27 | - 前向宣告 `std::` 名稱空間內的符號可能會導致未定義行為。 28 | - 有時候難以判斷應該使用前向宣告還是完整的 `#include`。 甚至有時替換掉 `#include` 可能會無聲無息地改變程式碼的意義： 29 | 30 | ```cpp 31 | // b.h: 32 | struct B {}; 33 | struct D : B {}; 34 | 35 | // good_user.cc: 36 | #include "b.h" 37 | void f(B*); 38 | void f(void*); 39 | void test(D* x) { f(x); } // 這裡會呼叫 f(B*) 40 | ``` 41 | 42 | 如果上面的程式碼中，將 `#include` 替換成 `B` 跟 `D` 的前向宣告的話，`test()` 就會變成呼叫 `f(void*)`。 43 | 44 | - 從標頭檔前向宣告多個符號，通常比直接 `#include` 更繁瑣且難以維護。 45 | - 為了使用前向宣告而調整程式架構（例如將物件成員改為指標成員），可能會使程式變慢或增加複雜度。 46 | 47 | ### 決定 48 | 49 | 盡量避免前向宣告其他專案中的實體。 50 | -------------------------------------------------------------------------------- /src/header-files/self-contained-headers.md: -------------------------------------------------------------------------------- 1 | ## 自給自足標頭檔 (Self-contained Headers) 2 | 3 | > 標頭檔應該要自給自足 (self-contained)，也就是說，應該能夠單獨被引入並正確編譯，而且副檔名必須是 `.h`。 其他具有插入目的，但不是標頭檔者，則應該要使用 `.inc` 作為副檔名，並且應該盡少使用。 4 | 5 | 所有標頭檔都應該要自給自足。 換句話說，使用者或者重構工具 (Refactoring Tool) 並不需要依賴任何額外的條件才能夠引入標頭檔。 更精確地說，標頭檔應該要包含 [標頭檔保護](define-guard.md)，而且應該要自己插入所有需要的其他標頭檔。 6 | 7 | 如果一個標頭檔內宣告了行內函式 (Inline Functions) 或模板 (Templates)，並且這些函式或模板將由標頭檔的使用者進行實例化的話，那麼它們的定義必須直接出現在標頭檔內，或是出現在該標頭檔所包含的其他檔案中。 不要將這些定義移至單獨的 `-inl.h` 文件。 這種作法以前很常見，但現在我們不允許這樣做。 如果某個模板的實例化僅發生在同一個 `.cc` 檔案中，無論是因為它被 [顯示實例化 (Explicit Instantiation)](https://en.cppreference.com/w/cpp/language/class_template#Explicit_instantiation) (譯註一)，或是因為其定義只有該 `.cc` 檔案可以存取，那麼該模板的定義可以放在 `.cc` 檔案內。 8 | 9 | 在某些極少數的狀況下，標頭檔可以不用是自給自足的。 這些特殊的標頭檔通常是用來載入程式碼到一些不尋常的位置，例如引入到另一個檔案的中間某個部位。 他們可以不使用 [標頭檔保護](define-guard.md)，而且可以不載入他們所需的檔案。 這種類型的檔案應該使用 `.inc` 作為副檔名。 應盡量避免使用這類檔案，並優先考慮使用自給自足的標頭檔。 10 | 11 | #### 譯註一：顯示實例化 (Explicit Instantiation) 說明 12 | 13 | 顯示實例化指的是在使用模板時，直接指示編譯器應該針對哪些型別生成對應的模板。 例如下面例子： 14 | 15 | `my_class.h`: 16 | 17 | ```cpp 18 | #ifndef MY_CLASS_H 19 | #define MY_CLASS_H 20 | 21 | template 22 | class MyClass { 23 | public: 24 | void DoSomething(); 25 | }; 26 | 27 | extern template class MyClass; // 宣告：MyClass 會被顯式實例化（但不在這裡） 28 | 29 | #endif // MY_CLASS_H 30 | ``` 31 | 32 | `my_class.cc`: 33 | 34 | ```cpp 35 | #include "my_class.h" 36 | 37 | template 38 | void MyClass::DoSomething() { 39 | // 實作內容 40 | } 41 | 42 | // 顯式實例化 43 | template class MyClass; // 只會在這個 `.cc` 檔案內產生 MyClass 的實例 44 | ``` 45 | 46 | 這個有別於一般常見的隱性實例化 (Implicit Instantiation) 的作法，也就是只有單純宣告模板，然後在真正要使用時才指定型別變數 `T` 對應的型別。 顯性實例化可以大幅提升編譯速度，因為它會確保整個程式編譯時模板只對指定的型別各生成一份類別的程式碼。 47 | -------------------------------------------------------------------------------- /src/classes/implicit-conversions.md: -------------------------------------------------------------------------------- 1 | ## 隱性轉換 (Implicit Conversions) 2 | 3 | > 不要定義隱性轉換。 轉換運算子和單一引數的建構函式應標記為 `explicit`。 4 | 5 | ### 定義 6 | 7 | 隱性轉換允許將一種型別 (稱為「來源型別」) 的物件用於原本預期另一種不同的型別 (稱為「目的型別」) 的地方，例如將一個 `int` 的引數傳給預期接受 `double` 引數的函式。 8 | 9 | 除了語言本身定義的隱性轉換之外，使用者也可以藉由在來源型別或目的型別的類別中加入適當的成員來自行定義。 若要在來源型別中定義隱性轉換，可透過定義一個名稱為目的型別的型別轉換運算子來完成（例如：`operator bool()`）。 若要在目的型別中定義隱性轉換，則是透過定義一個僅接受來源型別作為唯一引數的建構函式（或唯一沒有預設值的引數）來完成。 10 | 11 | 可以在建構函式或轉換運算子前加上 `explicit` 關鍵字，以確保只有在使用處明確指定目的型別（例如透過強制轉型）時才能使用。 這個限制除了應用於隱性轉換外，也會應用於 list 初始化語法： 12 | 13 | ```c++ 14 | class Foo { 15 | explicit Foo(int x, double y); 16 | ... 17 | } 18 | 19 | void Func(Foo f); 20 | ``` 21 | 22 | ```c++ 23 | Func({42, 3.14}); // 發生錯誤 24 | ``` 25 | 26 | 這類程式碼技術上來說並不算是隱性轉換，但是語言把它納入 `explicit` 關鍵字的適用範圍中。 27 | 28 | ### 優點 29 | 30 | - 當型別已經很明顯時，隱性轉換可以省去明確標示型別的必要，使程式更容易使用且更明瞭。 31 | - 隱性轉換可以當作比多載 (overloading) 更簡單的一種方案，例如一個接受 `string_view` 為引數的函式就可以同時代表接受 `string` 與 `const char*` 兩種型別的函式。 32 | - List 初始化語法是一種簡潔明瞭的初始化做法。 33 | 34 | ### 缺點 35 | 36 | - 隱性轉換會隱藏型別不合 (type-mismatch) 的 bug，像是目的型別不符合使用者的預期，或是使用者根本沒意識到有轉換發生。 37 | - 隱性轉換會讓程式碼難以閱讀，尤其在有多載函式時，會讓實際呼叫的程式碼變得不明確。 38 | - 單一引數的建構子可能會被意外地用於隱性型別轉換，就算這並非本意。 39 | - 如果一個單一引數的建構子沒有標註 `explicit`，並沒有一種可靠的方式能夠判斷到底是作者想要提供隱性轉換，還是只是單純忘記標註而已。 40 | - 隱性轉換可能導致呼叫處產生混淆，特別是在雙向隱性轉換存在時。 這可能發生於兩邊的型別都有實作隱性轉換，或者一邊的型別同時實作了隱性建構函式與隱性型別的轉換函式。 41 | - List 初始化在目的型別不明確時也會遭遇相同問題，特別是在 list 中只有一個元素的時候。 42 | 43 | ### 決定 44 | 45 | 型別轉換運算子與以單一引數呼叫的建構子必須在類別的定義中標註 `explicit`。 一個例外是，複製與轉移建構函式不應該是 `explicit`，因為他們並不會進行型別轉換。 46 | 47 | 隱性轉換在某些時候對於可以互換的型別來說可能是必要且恰當的，例如當某兩種型別其實只是底層數值的不同表示方式時就是如此。 如果遇到這種情況，請聯繫你的專案領導來豁免這條規則。 48 | 49 | 對於無法使用單一引數呼叫的建構子可以省略 `explicit`。 只接受單一 `std::initializer_list` 引述的建構函式也應該省略 `explicit`，以支援複製初始化語法 (copy-initalization, 例如：`MyType m = {1, 2};`)。 50 | -------------------------------------------------------------------------------- /src/naming/choosing-names.md: -------------------------------------------------------------------------------- 1 | ## 選擇名稱 (Choosing Names) 2 | 3 | > 為事物命名時，應使其目的與意圖對讀者而言清晰易懂，即使是來自不同團隊的讀者也能理解。 不必在意節省橫向空間，因為讓程式碼能被新讀者立即理解更為重要。 4 | 5 | 考慮該名稱可能被使用的情境。 名稱應該具有描述性，即使它會在離其定義處很遠的地方被使用，然而名稱不應重複當下語境中已經明示的資訊。 一般而言，名稱的描述性應該與其可見範圍成正比。 例如定義在標頭檔中的自由函式名稱可能會包含標頭檔所屬的函式庫名稱，而區域變數則不需要解釋它所屬的函式。 6 | 7 | 盡量減少使用對專案外的人來說可能不熟悉的縮寫（特別是縮寫成首字母的縮略字）。 不要透過刪除單字中的字母來產生縮寫。 如果要使用縮寫，偏好將縮寫視作單一單字並只將首字母大寫 (像是 `StartRpc()`，而不是 `StartRPC()`)。 有一個原則是，一個縮寫如果有被列在維基百科 (Wikipedia) 上的話，應該也可以接受。 注意有些普遍知道的縮寫是可以接受的，像是 `i` 作為疊代 (iteration) 次數以及 `T` 作為模板 (template) 參數。 8 | 9 | 你最常會看到的名稱與大多數名稱不同，極少數的「詞彙」名稱被廣泛重複使用，因此它們總是出現在適當語境中。 這些名稱傾向於很短或者甚至是縮寫，而他們完整的意思常來自於明確且完整的長篇文件而非僅靠名稱定義旁的註解或名稱本身的詞語來理解。 像是 `absl::Status` 在開發文件中有一個 [專門的頁面](https://abseil.io/docs/cpp/guides/status) 說明它正確的用法。 你大概不會很常定義新的詞彙名稱，但如果有的話，記得進行額外的設計審查，以確保該名稱在廣泛使用時仍保持合適。 10 | 11 | 好的例子： 12 | 13 | ```cpp 14 | class MyClass { 15 | public: 16 | int CountFooErrors(const std::vector& foos) { 17 | int n = 0; // 在有限的作用域與上下文中意圖明顯 18 | for (const auto& foo : foos) { 19 | ... 20 | ++n; 21 | } 22 | return n; 23 | } 24 | // 函式的註解不需解釋這個函式在錯誤時會回傳 non-OK 狀態，因為 `absl::Status` 25 | // 本身就自帶這個意思。 但可以用來記錄某些特定錯誤碼的行為。 26 | absl::Status DoSomethingImportant() { 27 | std::string fqdn = ...; // 這是 "Fully Qualified Domain Name" 的常見縮寫 28 | return absl::OkStatus(); 29 | } 30 | private: 31 | const int kMaxAllowedConnections = ...; // 在上下文中意圖明顯 32 | }; 33 | ``` 34 | 35 | 不好的例子： 36 | 37 | ```cpp 38 | class MyClass { 39 | public: 40 | int CountFooErrors(const std::vector& foos) { 41 | int total_number_of_foo_errors = 0; // 在有限作用域與上下文中顯得太冗長了 42 | for (int foo_index = 0; foo_index < foos.size(); ++foo_index) { // 建議使用慣用的 `i` 43 | ... 44 | ++total_number_of_foo_errors; 45 | } 46 | return total_number_of_foo_errors; 47 | } 48 | // `Result` 這個名稱過於通用，若無廣泛教學則難以理解其含義 49 | Result DoSomethingImportant() { 50 | int cstmr_id = ...; // 這種寫法刪除了單字內部的字母 51 | } 52 | private: 53 | const int kNum = ...; // 在這個較大的作用範圍內，這個名稱的意圖不明 54 | }; 55 | ``` 56 | -------------------------------------------------------------------------------- /src/header-files/names-and-order-of-includes.md: -------------------------------------------------------------------------------- 1 | ## `#include` 時的名稱與順序 2 | 3 | > 以右列順序引入標頭檔：相關的標頭檔、C 系統標頭檔、C++ 標準函式庫標頭檔、其他函式庫的標頭檔、你的專案的標頭檔。 4 | 5 | 所有標頭檔的路徑應該都要以專案的程式碼目錄為起點，並且不要使用 UNIX 資料夾別名，像是 `.` (現在目錄) 跟 `..` (上層目錄)。 舉例來說，`google-awesome-project/src/base/logging.h` 檔案應該要被這樣引入： 6 | 7 | ```cpp 8 | #include "base/logging.h" 9 | ``` 10 | 11 | 只有當函式庫要求時，才應該使用尖括號符號引入標頭檔。 準確來說，應該只有以下標頭檔必須使用尖括號： 12 | 13 | - C 與 C++ 的標準函式庫標頭檔（例如：`` 與 ``）。 14 | - POSIX、Linux 與 Windows 系統標頭檔（例如：`` 與 ``）。 15 | - 在少數情況中，第三方的函式庫（例如：``）。 16 | 17 | 假設現在有 `dir/foo.cc` 或 `dir/foo_test.cc` 檔案，目標是實作或測試 `dir2/foo2.h` 檔內的東西，那麼 `#include` 的順序應該這樣寫： 18 | 19 | 1. `dir2/foo2.h` 20 | 2. 空白行 21 | 3. C 系統檔，或是其他應該用尖括號引入且以 `.h` 為副檔名的標頭檔（例如：``、`` 與 ``）。 22 | 4. 空白行 23 | 5. C++ 標準函式庫標頭檔且不含副檔名（例如：`` 與 ``）。 24 | 6. 空白行 25 | 7. 其他函式庫的 `.h` 檔。 26 | 8. 空白行 27 | 9. 你的專案的 `.h` 檔。 28 | 29 | 注意所有有包含標頭檔的群組都應該以空白行分開。 30 | 31 | 依照這個順序，如果 `dir2/foo2.h` 遺漏了任何必要的 `#include`，那麼在建置 `dir/foo.cc` 或 `dir/foo_test.cc` 的時候就會中斷。 這樣可以確保建置錯誤會首先影響到這些文件的開發者，而不會影響到其他不相關的專案開發者。 32 | 33 | 上述例子中的 `dir/foo.cc` 與其直接相關的標頭檔 `dir2/foo2.h` 通常會放在同一個資料夾下，例如 `base/basictypes_test.cc` 跟 `base/basictypes.h`，但是有時候也有可能會分開放。 34 | 35 | 注意那些為了與 C 相容的標頭檔，像是 `stddef.h` 通常都有對應的 C++ 版本（例如 `cstddef`）。 雖然兩種版本都可以接受，但是記得要維持程式碼整體的一致性。 36 | 37 | 每個區塊中的檔案應該要依照字母順序排列。 要注意一些比較老的專案中可能沒有遵照這個規則，這些錯誤應在適當的時機進行修正。 38 | 39 | 例如 `google-awesome-project/src/foo/server/fooserver.cc` 檔中的 `#include` 可能長這樣： 40 | 41 | ```cpp 42 | #include "foo/server/fooserver.h" 43 | 44 | #include 45 | #include 46 | 47 | #include 48 | #include 49 | 50 | #include "base/basictypes.h" 51 | #include "foo/server/bar.h" 52 | #include "third_party/absl/flags/flag.h" 53 | ``` 54 | 55 | ### 例外 56 | 57 | 有時候，針對某些系統的程式碼可能需要條件式 `#include`，這種引入就可以放在所有 `#include` 之後。 當然，盡可能地讓這種程式碼越少且影響範圍越小越好。 58 | 59 | 例子： 60 | 61 | ```cpp 62 | #include "foo/public/fooserver.h" 63 | 64 | #include "base/port.h" // 可能有 LANG_CXX11 65 | 66 | #ifdef LANG_CXX11 67 | #include 68 | #endif // LANG_CXX11 69 | ``` 70 | -------------------------------------------------------------------------------- /src/background/goals-of-the-style-guide.md: -------------------------------------------------------------------------------- 1 | ## 風格指引的目標 2 | 3 | 為什麼會有這份文件？ 4 | 5 | 這邊有幾個核心目標是我們相信這份文件該提供的。 這些目標是所有規則的根本依據。 藉由提出這些想法，我們希望透過明確呈現這些理念，讓大家理解這些規則存在的原因，以及某些決策背後的考量。 如果你能了解每個規則是為了甚麼目標而制定，那大家應該也應該更清楚何時某些規定可以豁免（確實有些可以），以及要修改本指南的一條規定時該做出哪些爭論與考量。 6 | 7 | 這份文件的目標目前我們認為有以下幾點： 8 | 9 | ### 規則需要具有足夠的份量 10 | 11 | 一條風格規則所帶來的好處必須大到足夠合理來要求我們的工程師記住它。 它的好處是以沒有這份指南的情況下撰寫出的程式碼為準來衡量的。 有些規則可能在一些極端不好的程式碼中具有些微的好處，但是這種程式碼一般人不太可能會寫得出來的話，我們就不會寫進這份指引。 這個原則解釋了大多數我們沒有寫進的規則。 舉例來說，`goto` 違反了下面很多條原則，但是現在已經很少見了，因此這份風格指引就不討論它。 12 | 13 | ### 優化的對象應該是程式碼的讀者，而非撰寫者 14 | 15 | 我們預計我們的程式碼庫 (以及大多數提交到上面的各個組件) 會持續維護很長的一段時間。 因此大多數的時間會花在讀懂它，而非撰寫它。 我們明確選擇優先考量工程師在閱讀、維護與除錯程式碼時的體驗，而非撰寫的便利性。 「為讀者留下足跡」正是一種在這個原則之下常見的觀點：如果在一段程式碼中正在發生一些驚喜或者不尋常的事情 (例如：轉移一個指標的所有權)，在這裡留下一些文字上的提示將會非常有價值。 (`std::unique_ptr` 明確地在呼叫處提示了所有權轉移的行為)。 16 | 17 | ### 與現有的程式碼保持一致 18 | 19 | 在我們程式庫中使用一致的風格讓我們可以專注在其他 (更重要) 的問題。 一致性也促進了自動化：例如格式化工具或 `#include` 調整工具，只有在程式碼符合預期的一致性時才能正常運作。 在許多情況下，那些被歸類為「保持一致性」的規則，實際上是在說「選一個標準並遵循它，別再糾結」。 在那些情形允許彈性的潛在好處其實大於大家在那邊爭論所花費的時間。 然而，一致性也有其局限性：當沒有明確的技術論點，或缺乏長期發展方向時，它可以作為決策的參考，但也僅限於應用在局部範圍內（例如單個檔案，或一組緊密相關的介面）。 要注意一致性不應成為忽視新風格優勢或阻礙程式碼轉向新風格的理由。 20 | 21 | ### 適時與更大的 C++ 社群保持一致 22 | 23 | 跟其他組織使用 C++ 的方式保持一致所帶來的價值與在我們自己的程式庫中保持一致的理由是相同的。 如果一個 C++ 標準的特性可以解決一個問題，或者一個寫法被廣泛所知且接受，那就是一個使用它的有力理由。 然而，有時候這些特性與寫法可能具有某些缺陷，或者並不是我們的程式庫所需要的。 在這類情況下，其實更適合限制或者禁止這些特性。 在某些情形，沒有特別的好處或者足夠的價值讓我們轉換到標準介面上，我們會更傾向於使用我們自己撰寫或者第三方的函式庫。 24 | 25 | ### 避免令人驚訝或者危險的結構 26 | 27 | C++ 有著一些比看起來更令人訝異或者危險的特性。 這份風格指引內的部分限制就是為了要避免掉入這種陷阱裡。 風格指引對於豁免那些限制具有很高的標準，因為放棄那些規則很有可能會對程式的正確性造成很大的風險。 28 | 29 | ### 避免那些讓我們的一般 C++ 程式設計師認為詭異或者難以維護的結構 30 | 31 | 有些 C++ 的特性可能一般來說不太適合被使用，因為它們可能常造成一些額外的複雜性。 在一些廣泛被使用的程式碼中可能會適合使用這種特別的結構，因為複雜實作所帶來的好處會被廣泛使用這點放大，而且了解這些複雜東西的代價不需要在寫新一塊程式碼時再度付出一次。 如果有疑問的話，可以向專案領導詢問是否可以豁免這類的規則。 這對我們的程式庫來說尤其重要，因為程式碼的擁有者與團隊成員會隨時間變動，使得長期維護變得更具挑戰性：儘管現在正在使用某段程式碼的每個人都了解它，經過了幾年後也不能保證仍會是如此。 32 | 33 | ### 在我們的規模下要非常小心 34 | 35 | 對於一個超過 1 億行以及有著數千位工程師管理的程式庫來說，一個工程師的一些錯誤或者過於簡化的程式碼可能會對許多人造成極大的負擔。 舉例來說，要特別注意不能汙染全域命名空間 (global namespace)：如果大家都把東西放在全域命名空間的話，對於這種具有數億行程式碼的程式庫來說可能會很難避免命名衝突，並使得程式庫難以維護。 36 | 37 | ### 在必要時優先考量效能優化 38 | 39 | 雖然有些效能上的優化可能會牴觸這份文件的一些原則，但是對於必要的情況來說還是可接受的。 40 | 41 | ### 結論 42 | 43 | 這份文件的用意在於最大化地提供指引與適當的限制。 一如往常，我們盡量讓這些規則符合常識並維持良好的程式風格。 我們特別參考了整個 Google C++ 社群建立起的傳統，而非單獨考量你個人的喜好或者你的團隊。 當你遇到不尋常的結構時，請保持懷疑並謹慎使用：沒有限制它們並不代表你可以忽略它們。 此時請你自行判斷，如果你不太確定，請不要猶豫，立即詢問你的專案領導來取得意見。 44 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Google C++ Style Guide 繁體中文版 2 | 3 | [![Deploy](https://github.com/SLMT/google-cpp-style-guide-zh-tw/actions/workflows/deploy.yaml/badge.svg)](https://github.com/SLMT/google-cpp-style-guide-zh-tw/actions/workflows/deploy.yaml) 4 | 5 | 本書翻譯了 Google 官方訂定的 Coding Style (程式碼風格) 標準。 6 | 7 | 如果程式碼都能夠遵照同一份標準來撰寫的話，就能夠大大地增加程式的可讀性。 Google 所訂定的 C++ 程式碼風格非常明確，也非常仔細。 我認為是一個很不錯的標準。 8 | 9 | 不過可惜的是，Google 官方只有提供英文版的說明。 為了讓不善英文，並使用中文的人能夠理解文件的內容，特別翻譯本書供大家閱讀。 10 | 11 | ## 注意：本書正在更新到 2025 年版 12 | 13 | 本書自從 2021 年之後因為作者的私人原因沒有把翻譯完成。 在這段期間 Google 風格指南又經歷了多次修改，特別是參照的 C++ 版本從 C++11 版直接跳躍到 C++20。 同時也在規則中加入了許多 Abseil Library 的 [C++ Tips of The Week][7] 作為參考資料。 14 | 15 | 為了夠讓本中文版指南能夠跟上時代，作者正在積極校對與更新之前已翻譯的內容，同時也會盡快完成剩餘未完成的翻譯。 16 | 17 | 如果想要瞭解本指南的翻譯更新進度，請參考 GitHub 上的 [這個 issue][8]。 18 | 19 | ## 連結 20 | 21 | - 本書的 Github Repository：[https://github.com/SLMT/google-cpp-style-guide-zh-tw][1] 22 | - 線上電子書網址：[https://www.slmt.tw/google-cpp-style-guide-zh-tw/][2] 23 | - Google 官方 C++ Style 說明文件 (英文)：[https://google.github.io/styleguide/cppguide.html][3] 24 | 25 | ## 回報與修正 26 | 27 | 如果覺得哪裡翻譯有誤，或者覺得語句不通順，歡迎到 Github repository 的 [issue][4] 提出問題。 如果熟悉 Git 的話，也歡迎在 Github 上 fork 這個 repository 自行修改，並開啟 pull request 請求合併。 28 | 29 | ## 一些撰寫時的規則 30 | 31 | - 所有文句除標題外，一律以句號結尾。 32 | - 句號之後若還有其他語句在同一段，一律加上一個半形空白。 33 | - 英文單字與中文字詞的銜接處一律加上一個半形空白。 34 | 35 | ## 英文專有名詞的處理 36 | 37 | 這點我想了很久，有些程式中的關鍵字像是 class 或者 function 之類的，到底該使用中文的翻譯名詞呢？還是直接打英文名詞？ 38 | 39 | 使用中文專有名詞的好處是，對於直接從中文教材學習的人來說，很快就可以進入狀況。 不過有可能我翻譯的名詞與這些人當初所學的不同，這樣或許也沒有好處。 而且對於本來就學英文的人來說，一下子看到中文名詞可能很難進入狀況。 事實上，我個人平常是中英文夾雜使用的。 遇到專有名詞就切換成英文，一般解釋時就用中文。 但是無論如何，我必須要訂出一個統一的標準貫穿本書，以方便讀者閱讀。 40 | 41 | 我想來想去，覺得這本書主要的目還是在於翻譯。因此除了程式碼的部分外，盡量少用英文名詞較好。 所以我最後的方針是： 42 | 43 | > 除非是非得使用英文的情況，不然程式的專有名詞一律翻譯成中文。 少見名詞第一次出現時，在旁標明英文。 常用的名詞則直接使用中文翻譯。 44 | 45 | 為了方便只知道英文名詞的人能夠查閱看不懂翻譯的名詞，我在附錄列了一張[中英專有名詞的對照表](src/english-word-table.md)。 希望多少有點幫助。 46 | 47 | [1]: https://github.com/SLMT/google-cpp-style-guide-zh-tw 48 | [2]: https://www.slmt.tw/google-cpp-style-guide-zh-tw/ 49 | [3]: https://google.github.io/styleguide/cppguide.html 50 | [4]: https://github.com/SLMT/google-cpp-style-guide-zh-tw/issues 51 | [5]: https://github.com/google/styleguide/blob/63107a12eb85a4da33e2585a912234e4794cea06/cppguide.html 52 | [6]: https://github.com/google/styleguide/ 53 | [7]: https://abseil.io/tips/ 54 | [8]: https://github.com/SLMT/google-cpp-style-guide-zh-tw/issues/7 55 | -------------------------------------------------------------------------------- /src/README.md: -------------------------------------------------------------------------------- 1 | # Google C++ Style Guide 繁體中文版 2 | 3 | [![Deploy](https://github.com/SLMT/google-cpp-style-guide-zh-tw/actions/workflows/deploy.yaml/badge.svg)](https://github.com/SLMT/google-cpp-style-guide-zh-tw/actions/workflows/deploy.yaml) 4 | 5 | 本書翻譯了 Google 官方訂定的 Coding Style (程式碼風格) 標準。 6 | 7 | 如果程式碼都能夠遵照同一份標準來撰寫的話，就能夠大大地增加程式的可讀性。 Google 所訂定的 C++ 程式碼風格非常明確，也非常仔細。 我認為是一個很不錯的標準。 8 | 9 | 不過可惜的是，Google 官方只有提供英文版的說明。 為了讓不善英文，並使用中文的人能夠理解文件的內容，特別翻譯本書供大家閱讀。 10 | 11 | ## 注意：本書正在更新到 2025 年版 12 | 13 | 本書自從 2021 年之後因為作者的私人原因沒有把翻譯完成。 在這段期間 Google 風格指南又經歷了多次修改，特別是參照的 C++ 版本從 C++11 版直接跳躍到 C++20。 同時也在規則中加入了許多 Abseil Library 的 [C++ Tips of The Week][7] 作為參考資料。 14 | 15 | 為了夠讓本中文版指南能夠跟上時代，作者正在積極校對與更新之前已翻譯的內容，同時也會盡快完成剩餘未完成的翻譯。 16 | 17 | 如果想要瞭解本指南的翻譯更新進度，請參考 GitHub 上的 [這個 issue][8]。 18 | 19 | ## 連結 20 | 21 | - 本書的 Github Repository：[https://github.com/SLMT/google-cpp-style-guide-zh-tw][1] 22 | - 線上電子書網址：[https://www.slmt.tw/google-cpp-style-guide-zh-tw/][2] 23 | - Google 官方 C++ Style 說明文件 (英文)：[https://google.github.io/styleguide/cppguide.html][3] 24 | 25 | ## 回報與修正 26 | 27 | 如果覺得哪裡翻譯有誤，或者覺得語句不通順，歡迎到 Github repository 的 [issue][4] 提出問題。 如果熟悉 Git 的話，也歡迎在 Github 上 fork 這個 repository 自行修改，並開啟 pull request 請求合併。 28 | 29 | ## 一些撰寫時的規則 30 | 31 | - 所有文句除標題外，一律以句號結尾。 32 | - 句號之後若還有其他語句在同一段，一律加上一個半形空白。 33 | - 英文單字與中文字詞的銜接處一律加上一個半形空白。 34 | 35 | ## 英文專有名詞的處理 36 | 37 | 這點我想了很久，有些程式中的關鍵字像是 class 或者 function 之類的，到底該使用中文的翻譯名詞呢？還是直接打英文名詞？ 38 | 39 | 使用中文專有名詞的好處是，對於直接從中文教材學習的人來說，很快就可以進入狀況。 不過有可能我翻譯的名詞與這些人當初所學的不同，這樣或許也沒有好處。 而且對於本來就學英文的人來說，一下子看到中文名詞可能很難進入狀況。 事實上，我個人平常是中英文夾雜使用的。 遇到專有名詞就切換成英文，一般解釋時就用中文。 但是無論如何，我必須要訂出一個統一的標準貫穿本書，以方便讀者閱讀。 40 | 41 | 我想來想去，覺得這本書主要的目還是在於翻譯。因此除了程式碼的部分外，盡量少用英文名詞較好。 所以我最後的方針是： 42 | 43 | > 除非是非得使用英文的情況，不然程式的專有名詞一律翻譯成中文。 少見名詞第一次出現時，在旁標明英文。 常用的名詞則直接使用中文翻譯。 44 | 45 | 為了方便只知道英文名詞的人能夠查閱看不懂翻譯的名詞，我在附錄列了一張[中英專有名詞的對照表](src/english-word-table.md)。 希望多少有點幫助。 46 | 47 | [1]: https://github.com/SLMT/google-cpp-style-guide-zh-tw 48 | [2]: https://www.slmt.tw/google-cpp-style-guide-zh-tw/ 49 | [3]: https://google.github.io/styleguide/cppguide.html 50 | [4]: https://github.com/SLMT/google-cpp-style-guide-zh-tw/issues 51 | [5]: https://github.com/google/styleguide/blob/63107a12eb85a4da33e2585a912234e4794cea06/cppguide.html 52 | [6]: https://github.com/google/styleguide/ 53 | [7]: https://abseil.io/tips/ 54 | [8]: https://github.com/SLMT/google-cpp-style-guide-zh-tw/issues/7 55 | -------------------------------------------------------------------------------- /src/scoping/thread-local-variables.md: -------------------------------------------------------------------------------- 1 | ## `thread_local` 變數 2 | 3 | > 對於不是在 function 內宣告的 `thread_local` 變數，一定要以真編譯期常數 (true compile-time constant) 來初始化，這一點必須透過 [`constinit`](https://en.cppreference.com/w/cpp/language/constinit) 屬性來強制執行。 偏好使用 `thread_local` 來定義執行緒內資料 (thread-local data)。 4 | 5 | ### 定義 6 | 7 | 變數可以在宣告時加上 `thread_local` 修飾詞： 8 | 9 | ```cpp 10 | thread_local Foo foo = ...; 11 | ``` 12 | 13 | 這類變數實際上是多個物件的集合，因此當不同的執行緒存取它時，實際上是在存取不同的物件。 `thread_local` 變數其實在很多方面與 [靜態儲存期變數](static-and-global-variables.md) 很接近。 舉例來說，它們可以被宣告在命名空間的作用域、函式內部、或是做為類別的靜態成員，但不能做為一般類別的成員。 14 | 15 | `thread_local` 變數的初始化很像靜態變數的作法，只差在它們必須在每個執行緒裡面分別初始化，而不是在程式啟動時一次初始化。 這代表著那些在函式內宣告的 `thread_local` 變數很安全，但是其他的 `thread_local` 變數則會像靜態變數一樣遭遇初始化順序的問題 (以及其他更多問題)。 16 | 17 | `thread_local` 變數有一個微妙的解構順序問題： 在執行緒結束的時候，`thread_local` 變數會依照他們被初始化的相反順序進行解構 (在 C++ 通常是這樣)。 如果發生任何被解構函式觸動的程式碼參考了任何該執行緒內已經被銷毀的 `thread_local` 變數，那對我們來說會變得很難去分析釋出後使用 (use-after-free) 的問題。 18 | 19 | ### 優點 20 | 21 | - 執行緒內資料從本質上來說不會受到資料競爭 (data race) 影響 (因為只有一個執行緒可以存取)，這點讓 `thread_local` 對並行程式設計很有幫助。 22 | - `thread_local` 是唯一標準用來建立執行緒內變數 (thread-local variables) 的方式。 23 | 24 | ### 缺點 25 | 26 | - 在執行緒啟動或者初次存取 `thread_local` 的變數時，可能會觸發無法預測且數量不可控的額外程式碼執行。 27 | - `thread_local` 變數本質上與全域變數無異，因此它具有全域變數的所有缺點，唯一的例外是它是執行緒安全的 (thread safe)。 28 | - `thread_local` 變數帶來的記憶體消耗會隨著執行緒數量增加而變大，有可能會造成很大的負擔。 29 | - 一般類別的成員除非是 `static`，不然就不能是 `thread_local`。 30 | - 如果 `thread_local` 變數有很複雜的解構函式，那可能會遭遇到釋出後使用 (use-after-free) 的問題。 特別是這類變數的解構函式不得間接或直接存取任何可能已被銷毀的 `thread_local` 資料。 但這件事情也很難被強制。 31 | - 對於防範全域或靜態資料發生釋出後使用問題的方法並無法用在 `thread_local` 資料上。 確切來說，我們可以允許略過全域或靜態變數的解構函數，因為他們的生存期止於程式結束。 因此，任何洩漏問題會由作業系統的資源與記憶體清理機制進行處理。 相反地，在程式執行中結束的執行緒若是略過 `thread_local` 變數的解構函式的話，可能會導致資源洩漏，其規模與程式執行期間終止的執行緒總數成正比。 32 | 33 | ### 決定 34 | 35 | 對於類別與名稱空間作用域內的 `thread_local` 變數，一定要以真編譯期常數 (true compile-time constant) 來初始化 (換言之，他們不能用動態初始化)。 為了要強制這點，類別與名稱空間作用域內的 `thread_local` 變數一定要標註 [`constinit`](https://en.cppreference.com/w/cpp/language/constinit) (或是 `constexpr`，但須盡量少用)： 36 | 37 | ```cpp 38 | constinit thread_local Foo foo = ...; 39 | ``` 40 | 41 | 定義在函式內的 `thread_local` 變數沒有初始化疑慮，但在執行緒結束時可能會有釋出後使用 (use-after-free) 的問題。 注意你可以利用定義一個會回傳 `thread_local` 變數的函式或靜態方法，來使用函式作用域等級的 `thread_local` 變數，以模擬類別或是命名空間作用域等級的 `thread_local`： 42 | 43 | ```cpp 44 | Foo& MyThreadLocalFoo() { 45 | thread_local Foo result = ComplicatedInitialization(); // 函式名稱：很複雜的初始化 46 | return result; 47 | } 48 | ``` 49 | 50 | 注意 `thread_local` 變數會在執行緒結束時銷毀。 如果任何此類變數的解構函式用到其他可能被摧毀的 `thread_local` 變數，都可能會造成難以診斷的釋出後使用錯誤。 因此，宣告 `thread_local` 變數時應優先選擇簡單型別 (trivial type)，或確保在解構時不會執行使用者提供的程式碼，以降低誤用已刪除的 `thread_local` 變數的風險。 51 | 52 | 應優先使用 `thread_local` 來定義執行緒內資料。 53 | -------------------------------------------------------------------------------- /src/SUMMARY.md: -------------------------------------------------------------------------------- 1 | # Summary 2 | 3 | [本書介紹](README.md) 4 | 5 | ------------------------------ 6 | 7 | - [背景](background/README.md) 8 | - [風格指引的目標](background/goals-of-the-style-guide.md) 9 | - [C++ 版本](cpp-version.md) 10 | - [標頭檔 (Header Files)](header-files/README.md) 11 | - [自給自足標頭檔](header-files/self-contained-headers.md) 12 | - [#define 保護](header-files/define-guard.md) 13 | - [引入你需要的](header-files/include-what-you-use.md) 14 | - [前向宣告](header-files/forward-declarations.md) 15 | - [行內函式](header-files/inline-functions.md) 16 | - [#include 時的名稱與順序](header-files/names-and-order-of-includes.md) 17 | - [作用域 (Scoping)](scoping/README.md) 18 | - [名稱空間](scoping/namespaces.md) 19 | - [內部鏈結](scoping/internal-linkage.md) 20 | - [非成員、靜態成員、全域函式](scoping/nonmember-static-members.md) 21 | - [區域變數](scoping/local-variables.md) 22 | - [靜態與全域變數](scoping/static-and-global-variables.md) 23 | - [thread_local 的變數](scoping/thread-local-variables.md) 24 | - [類別 (Classes)](classes/README.md) 25 | - [在建構子內工作](classes/doing-work-in-constructor.md) 26 | - [隱性轉換](classes/implicit-conversions.md) 27 | - [可複製與可轉移的型別](classes/copyable-and-movable-types.md) 28 | - [結構與類別的比較](classes/structs-vs-classes.md) 29 | - [結構與結構與對和元組的比較](classes/struct-vs-paris-and-tuples.md) 30 | - [🚧 繼承](work-in-progress.md) 31 | - [🚧 運算子多載](work-in-progress.md) 32 | - [🚧 存取控制](work-in-progress.md) 33 | - [🚧 宣告順序](work-in-progress.md) 34 | - [🚧 函式 (Functions)](work-in-progress.md) 35 | - [🚧 Google 特有的魔術](work-in-progress.md) 36 | - [🚧 其他 C++ 特性](other-cpp-features/README.md) 37 | - [🚧 例外](other-cpp-features/exceptions.md) 38 | - [🚧 模板元程式設計](other-cpp-features/template-metaprogramming.md) 39 | - [🚧 別名](other-cpp-features/alias.md) 40 | - [🚧 預處理器巨集](other-cpp-features/preprocessor-marcos.md) 41 | - [命名 (Naming)](naming/README.md) 42 | - [選擇名稱](naming/choosing-names.md) 43 | - [檔案名稱](naming/file-names.md) 44 | - [型別名稱](naming/type-names.md) 45 | - [概念名稱](naming/concept-names.md) 46 | - [變數名稱](naming/variable-names.md) 47 | - [常數名稱](naming/constant-names.md) 48 | - [函數名稱](naming/function-names.md) 49 | - [名稱空間名稱](naming/namespace-names.md) 50 | - [列舉器名稱](naming/enumerator-names.md) 51 | - [模板參數名稱](naming/template-parameter-names.md) 52 | - [巨集名稱](naming/macro-names.md) 53 | - [別名](naming/aliases.md) 54 | - [名稱規則的例外](naming/exceptions-to-naming-rules.md) 55 | - [🚧 註解](work-in-progress.md) 56 | - [🚧 排版](work-in-progress.md) 57 | - [🚧 規則中的例外](work-in-progress.md) 58 | - [🚧 結尾贈言](work-in-progress.md) 59 | 60 | ------------------------------ 61 | 62 | [附錄：中英文名詞對照](english-word-table.md) 63 | -------------------------------------------------------------------------------- /src/classes/copyable-and-movable-types.md: -------------------------------------------------------------------------------- 1 | ## 可複製與可轉移的型別 (Copyable and Movable Types) 2 | 3 | > 一個類別的公用 API 應該要清楚表明該類別是可複製、只能轉移、或者不能複製也不能轉移的型別。 在複製與/或轉移對你的型別具有明顯意義時應提供這些操作。 4 | 5 | ### 定義 6 | 7 | 一個可轉移的型別是指可以從暫時變數初始化 (initialization) 或者指派 (assignment) 的型別。 8 | 9 | 一個可複製的型別是指可以從相同型別的任意物件初始化或者指派的型別 (因此定義上來說也是可轉移的)，但規定來源物件的值不得被改變。 `std::unique_ptr` 就是一個可轉移但不可複製的型別範例，因為來源 `std::unique_ptr` 會在指派的時候被修改。 `int` 跟 `std::string` 則是可轉移且可複製型別的範例，其中對 `int` 來說轉移與複製的動作是相同的，對 `std::string` 來說轉移操作的成本低於複製操作。 10 | 11 | 對於使用者自行定義的型別來說，複製的行為是由複製建構子與複製指派運算子定義。 如果有轉移建構子與轉移指派運算子的話，轉移的行為由這些函式定義；如果沒有的話，則由複製建構子與複製指派運算子定義。 12 | 13 | 複製或轉移建構子可以被編譯器隱含呼叫，例如在以傳值 (pass by value) 方式傳遞物件給函式時。 14 | 15 | ### 優點 16 | 17 | 可複製與轉移的型別的物件可以用於以值傳遞與回傳 (pass and return by value)，這讓 API 更簡單、更安全以及更具通用性。 不像傳指標 (pass by pointer) 或參考 (pass by reference) 的方式，這些型別不會造成所有權、生存期、修改性以及其他類似的問題，而且也不需要在介面合約中加以說明。 它也避免用戶端與實作之間產生非局部的互動，這讓他們更容易被理解、維護與被編譯器優化。 更甚者，這些物件可以被那些要求傳值呼叫的泛用 API 使用，例如大多數的容器，而且也允許額外的彈性，例如型別組合 (type composition)。 18 | 19 | 複製或轉移建構子和指派運算子通常比起其他選擇像是 `Clone()`、`CopyFrom()` 或者 `Swap()` 更容易定義，因為這些函式可以透過編譯器隱含或者透過 `=` 預設函式產生。 這些函式簡潔，並可確保所有資料成員都被正確複製。 複製與轉移建構子通常更有效率，因為他們不需要分配 heap 空間或者額外的初始化或指派動作，而且他們也適用於許多優化，像是複製省略 (copy elision)。 20 | 21 | 轉移運算子允許從右值物件 (rvalue object) 中隱性且高效地將資源移出。 這允許在某些狀況下寫出更簡潔直觀的程式碼。 22 | 23 | ### 缺點 24 | 25 | 有些型別不需要是可以複製的，而且對於這些型別來說提供複製操作可能令人困惑、不合邏輯，甚至完全錯誤。 像是代表單例 (singleton) 的物件 (`Registerer`)、物件綁定在特定作用域 (`Cleanup`) 或緊密連結物件身分 (`Mutex`) 的型別無法以有意義的方式複製。 用於具多型用途之基底類別的複製操作是危險的，因為可能會造成[物件切割 (object slicing)](https://en.wikipedia.org/wiki/Object_slicing) 的狀況。 預設或者缺乏細心實作的複製操作可能會不正確，並且可能導致難以察覺或診斷的錯誤。 26 | 27 | 複製建構子是隱性呼叫的，這使得呼叫處容易被忽略，而且可能會讓那些習慣傳參考呼叫 (pass by reference) 的程式語言的程式設計師感到困惑。 這也可能會鼓勵過度使用複製，並進一步造成效能問題。 28 | 29 | ### 決定 30 | 31 | 每一個類別的公用界面必須清楚定義該類別支援哪些複製與轉移操作。 這應該要透過在類別宣告的公用 (public) 區域明確宣告以及/或刪除適當的運算子來達到。 32 | 33 | 具體來說，一個可複製的類別應該明確宣告複製運算子；一個只能轉移的類別應該明確宣告轉移運算子；一個不能複製或轉移的類別應該明確刪除複製運算子。 一個可複製的型別可以額外宣告轉移運算子來提供更高效的轉移操作。 可以選擇明確宣告或刪除所有四種複製與轉移操作，但這並非必要。 如果你提供複製或轉移指派運算子，則必須同時提供對應的建構子。 34 | 35 | ```cpp 36 | class Copyable { 37 | public: 38 | Copyable(const Copyable& other) = default; 39 | Copyable& operator=(const Copyable& other) = default; 40 | 41 | // 上述宣告會抑制隱式的轉移操作 42 | // 你可以透過明確宣告轉移操作來提供高效的轉移 43 | }; 44 | 45 | class MoveOnly { 46 | public: 47 | MoveOnly(MoveOnly&& other) = default; 48 | MoveOnly& operator=(MoveOnly&& other) = default; 49 | 50 | // 複製操作會被隱性刪除，但若有需要，也可以明確地宣告： 51 | MoveOnly(const MoveOnly&) = delete; 52 | MoveOnly& operator=(const MoveOnly&) = delete; 53 | }; 54 | 55 | class NotCopyableOrMovable { 56 | public: 57 | // 不可以複製且不可以轉移 58 | NotCopyableOrMovable(const NotCopyableOrMovable&) = delete; 59 | NotCopyableOrMovable& operator=(const NotCopyableOrMovable&) 60 | = delete; 61 | 62 | // 轉移操作會被隱性禁用，但若有需要，也可以明確地宣告： 63 | NotCopyableOrMovable(NotCopyableOrMovable&&) = delete; 64 | NotCopyableOrMovable& operator=(NotCopyableOrMovable&&) 65 | = delete; 66 | }; 67 | ``` 68 | 69 | 只有在這些宣告或刪除的行為明顯可推導時，才可以省略： 70 | 71 | - 如果一個類別沒有私有 (private) 區域，像是一個 [struct](./structs-vs-classes.md) 或者純介面基底類別，則其是否可複製或可轉移，可由其公開資料成員決定。 72 | - 如果一個基底類別明顯不是可複製或轉移的，那麼它的衍伸類別自然也不會是。 一個純介面基底類別如果讓這些操作隱性定義的話，並不足以讓具體子類別的特性明確。 73 | - 注意如果你明確宣告或刪除了複製建構子或者複製指派運算子的話，另一個複製操作便不再是明確的，必須一併明確宣告或刪除。 轉移操作也相同。 74 | 75 | 如果一個類別的複製與轉移對一般使用者來說不明確，或者這些操作可能會造成不可預期的代價，則不應將其設計為可複製或可轉移的。 可複製型別的轉移操作本質上屬於效能優化，而且是潛在造成錯誤與複雜性的源頭，因此除非定義它們可以顯著地相較於複製操作提升效能，否則應避免定義。 如果你的型別提供複製操作，建議設計你的類別讓其預設的複製行為是正確的。 務必如同檢查其他程式碼一般，審視所有預設操作的正確性。 76 | 77 | 為了消除物件切割 (object slicing) 的風險，偏好將基底類別定義為抽象的 (abstract)，這可透過右列方式實現：將建構子宣告為 `protected`、將解構子宣告為 `protected` 或者給它們一或更多的虛擬成員函式 (virtual member function)。 偏好避免從具體類別 (concrete class) 繼承。 78 | -------------------------------------------------------------------------------- /src/english-word-table.md: -------------------------------------------------------------------------------- 1 | # 附錄：常用專有名詞中英對照表 2 | 3 | 下表以英文名詞按照字母順序排序 4 | 5 | | 英文 (English) | 繁體中文 (Traditional Chinese) | 6 | | :--------------------- | :----------------------------- | 7 | | Alias | 別名 | 8 | | Array | 陣列 | 9 | | Base Class | 基底類別 | 10 | | Bug | 錯誤 | 11 | | Class | 類別 | 12 | | Compile | 編譯 | 13 | | Compiler | 編譯器 | 14 | | Constructor | 建構函式 | 15 | | Data Race | 資料競爭 | 16 | | Declaration | 宣告 | 17 | | Define, Definition | 定義 | 18 | | Dependency | 依賴關係 | 19 | | Destructor | 解構函式 | 20 | | Directory | 資料夾、目錄 | 21 | | Entity | 實體 | 22 | | Enumerator | 列舉器 | 23 | | Explicit Instantiation | 顯式實例化 | 24 | | Expression | 表示式 | 25 | | External Linkage | 外部連結性 | 26 | | Forward Declaration | 前向宣告 | 27 | | Function | 函式 | 28 | | Functor | 函子 | 29 | | Global Scope | 全域 | 30 | | Handler | (尚無翻譯) | 31 | | Header, Header File | 標頭檔 | 32 | | Implicit Instantiation | 隱性實例化 | 33 | | Inline Function | 行內函式 | 34 | | Instance | 實例 | 35 | | Internal Linkage | 內部鏈結 | 36 | | Input | 輸入值 | 37 | | Iteration | 疊代 | 38 | | Library | 函式庫 | 39 | | Lifetime | 存活期 | 40 | | Link | 連結 | 41 | | Linker | 連結器 | 42 | | Literal | 字面值 | 43 | | Local | 局部的 | 44 | | Loop | 迴圈 | 45 | | Namespace | 命名空間 | 46 | | Object Code | 目的碼 | 47 | | Object File | 目的碼檔 | 48 | | Output | 輸出值 | 49 | | Overloading | 多載 | 50 | | Parameter | 參數 | 51 | | Pointer | 指標 | 52 | | Prefix | 前綴 | 53 | | Private | 私有的 | 54 | | Private Member | 私有成員 | 55 | | Public | 公用的 | 56 | | Public Member | 公用成員 | 57 | | Raw Pointer | 原始指標 | 58 | | Reference | 參考 | 59 | | Smart Pointer | 智慧指標 | 60 | | Statement | 陳述句 | 61 | | Static Data Member | 靜態資料成員 | 62 | | Static Member Function | 靜態成員函式 | 63 | | Storage Duration | 儲存期 | 64 | | Struct | 結構 | 65 | | Subclass | 子類別 | 66 | | Symbol | 符號 | 67 | | Transitive Inclusion | 傳遞式引入 | 68 | | Template | 模板 | 69 | | Thread | 執行緒 | 70 | | Type | 型別 | 71 | | Unnamed Namespaces | 無名名稱空間 | 72 | | Virtual Destructor | 虛擬解構函式 | 73 | | Virtual Function | 虛擬函式 | 74 | -------------------------------------------------------------------------------- /src/scoping/static-and-global-variables.md: -------------------------------------------------------------------------------- 1 | ## 靜態與全域變數 2 | 3 | > 除非它們是可平凡解構的 ([trivially destructible](http://en.cppreference.com/w/cpp/types/is_destructible))，否則禁止使用具有靜態儲存期 ([static storage duration](http://en.cppreference.com/w/cpp/language/storage_duration#Storage_duration)) 的物件。 簡單來說，這表示該物件的解構函式不執行任何操作，即便考慮其成員與基底類別的解構函式也是如此。 正式地說，這表示該類型沒有使用者自定義的解構函式，也沒有虛擬解構函式 (virtual destructor)，而且他的基底類別跟非靜態成員都是可平凡解構的。 函式內部的靜態變數可以使用動態初始化。 不建議對靜態類別成員變數或命名空間作用域內的變數使用動態初始化，但在有限的情況下可以接受。 詳情請看下面說明。 4 | 5 | 一個基本原則：若某個全域變數的宣告本身能夠是 `constexpr` (常數表示式)，則它自然符合這些要求。 6 | 7 | ### 定義 8 | 9 | 每個物件都有儲存期 (storage duration)，這與他的存活期 (lifetime) 相關。 有著靜態儲存期 (static storage duration) 的物件從被初始化開始會一路存活到程式結束。 這種物件可能是命名空間作用域內的一個 (全域) 變數、類別的靜態資料成員或是函式中帶有 `static` 修飾詞的區域變數。 函式靜態區域變數會在程式第一次經過他的宣告時被初始化；所有其他有著靜態儲存期的物件則作為程式啟動的一部分而同時被初始化。 所有有著靜態儲存期的物件在程式結束時被摧毀 (發生在所有尚未合併的執行緒終止之前)。 10 | 11 | 初始化可以是*動態的*，這表示初始化過程中可能涉及非平凡 (non-trivial) 的操作。 (例如：一個動態分配記憶體，或是使用現在程序的 ID 進行初始化的建構函式。) 其他類的初始化都叫做*靜態的*初始化，不過這兩者並不是完全相對的： 有著靜態儲存期的物件**總是**會先靜態初始化 (例如用一個常數或者是一組全部都是零的位元初始化變數)，然後需要的話才會再進行動態初始化。 12 | 13 | ### 優點 14 | 15 | 全域與靜態變數對於很多應用來說非常好用： 具名常數、一些轉換元件中的輔助資料結構、命令提示的旗標 (flag)、日誌、註冊機制、背景基礎設施等等。 16 | 17 | ### 缺點 18 | 19 | 全域與靜態變數使用動態初始化或者不平凡的解構函式而產生的複雜度容易導致難以尋找的錯誤。 動態初始化在轉換元件之間或者解構時沒有被排序 (除了那種在反向初始化時的解構動作)。 當一個初始化指向另一個有著靜態儲存期的變數時，有可能會導致一個物件在他的存活期開始前 (或者結束之後) 被存取。 更甚者，當一個程式啟動了一些在結束時不會合併的執行緒，這些執行緒可能會存取已經超出存活期的物件 (若該物件的解構函式已經執行完畢)。 20 | 21 | ### 決定 22 | 23 | #### 對於解構函式 24 | 25 | 當解構函式是平凡的 (trivial)，他的執行完全並不會被順序所影響 (因為他們基本上不會執行)； 否則，我們可能會面臨在物件存活期結束後仍然存取它們的風險。 因此只有當物件是可平凡解構的時，我們才允許它們擁有靜態儲存期。 基礎型別 (像是指標或者 `int`) 都是可平凡解構的，這些型別的陣列也都是。 請注意，使用 `constexpr` 標示的變數都是可平凡解構的。 26 | 27 | ```cpp 28 | const int kNum = 10; // 允許 29 | 30 | struct X { int n; }; 31 | const X kX[] = {{1}, {2}, {3}}; // 允許 32 | 33 | void foo() { 34 | static const char* const kMessages[] = {"hello", "world"}; // 允許 35 | } 36 | 37 | // 允許: constexpr 保證該變數可平凡解構 38 | constexpr std::array kArray = {{1, 2, 3}}; 39 | ``` 40 | 41 | ```cpp 42 | // 不好: 非可平凡解構的物件 43 | const string kFoo = "foo"; 44 | 45 | // 即使 kBar 是參考 (reference)，仍涉及非平凡解構。 46 | // 注意: 此規則亦適用於存活期延長的臨時物件。 47 | const string& kBar = StrCat("a", "b", "c"); 48 | 49 | void bar() { 50 | // 不好: 非可平凡解構函式 51 | static std::map kData = {{1, 0}, {2, 0}, {3, 0}}; 52 | } 53 | ``` 54 | 55 | 請注意，參考 (reference) 不是物件，因此不受解構性的限制影響。 不過動態初始化的限制仍然適用。 特別是具有 `static T& t = *new T;` 形式的函式內區域靜態變數是允許的。 56 | 57 | #### 對於初始化 58 | 59 | 初始化是一個更複雜的主題。 因為我們不只要考慮類別的建構式是否執行，也要考慮初始化時的計算： 60 | 61 | ```cpp 62 | int n = 5; // 可以 63 | int m = f(); // ? (根據 f 的行為決定) 64 | Foo x; // ? (根據 Foo::Foo 的行為決定) 65 | Bar y = g(); // ? (根據 g 與 Bar::Bar 的行為決定) 66 | ``` 67 | 68 | 除了第一式之外都帶來不確定的初始化順序問題。 69 | 70 | 我們這邊想要表達的概念在 C++ 標準的正式語言中稱為「常數初始化 (Constant Initialization)」。 這代表初始化的表示式 (expression) 是一個常數表示式 (constant expresion)，而且如果物件是透過建構函式初始化，那麼該建構函式也一定要被標記 `constexpr`： 71 | 72 | ```cpp 73 | struct Foo { constexpr Foo(int) {} }; 74 | 75 | int n = 5; // 可以，5 是一個常數表示式 76 | Foo x(2); // 可以，2 是一個常數表示式，而且選擇的建構函式也是 constexpr 77 | Foo a[] = { Foo(1), Foo(2), Foo(3) }; // 可以 78 | ``` 79 | 80 | 我們一律允許常數初始化。 靜態儲存期的變數若使用常數初始化的話，應標上 `constexpr` 或 `constinit`。 任何沒有依照這種方式標記的非區域靜態儲存期變數應該要假定是使用動態初始化，並且在審查時要特別小心。 81 | 82 | 作為反例，以下初始化是有問題的： 83 | 84 | ```cpp 85 | // 一些宣告 86 | time_t time(time_t*); // 沒有使用 constexpr！ 87 | int f(); // 沒有使用 constexpr！ 88 | struct Bar { Bar() {} }; 89 | 90 | // 有問題的初始化 91 | time_t m = time(nullptr); // 初始化的表示式並非是常數表示式 92 | Foo y(f()); // 同上 93 | Bar b; // 選用的建構函數 Bar::Bar() 也不是 constexpr 94 | ``` 95 | 96 | 我們不鼓勵對於非區域變數使用動態初始化，而且通常來說也不允許。 然而，如果程式中沒有任何層面依賴該初始化與其他初始化之間的順序的話，我們就允許這麼做。 在這樣的限制下，初始化間的順序並不會產生可見的差異。 例如： 97 | 98 | ```cpp 99 | int p = getpid(); // 允許，只要沒有其他靜態變數使用 p 來初始化就好 100 | ``` 101 | 102 | 我們允許對區域靜態變數使用動態初始化 (而且很常用)。 103 | 104 | #### 常見模式 105 | 106 | - 全域字串： 如果需要一個具名的全域或者靜態字串，請考慮使用右列的 `constexpr` 變數：`string_view` (在 Abseil 函式庫中)、字元陣列、或是指向字串字面值 (string literal) 的字元指標。 字串字面值本來就有靜態儲存期，而且通常就夠用。 詳情請參考 [TotW #140](https://abseil.io/tips/140)。 107 | - Map、Set、以及其他動態容器： 如果你要求使用靜態的固定集合，像是一個 Set 或是一個查詢表，你不能使用標準函式庫的動態容器作為靜態變數，因為他們具有非平凡的解構函式。 反之，請考慮使用一個包含平凡型別的簡單陣列，例如使用一個整數的陣列的陣列來表示一個從整數映射到另一組整數的關係，或是一個整數與字元指標的 `Pair` 陣列表示整數映射到字串的關係。 對於小的資料集，線性搜尋就很夠了 (而且因為記憶體局部性 (memory locality) 的關係還很有效率)。 可以考慮使用 [`absl/algorithm/container.h`](https://github.com/abseil/abseil-cpp/blob/master/absl/algorithm/container.h) 來對他們進行一些標準操作。 如果必要的話，保持集合的排序，以便使用二元搜尋 (binary search)。 如果你真的比較想使用標準函式庫的動態容器，請考慮使用函式內的靜態指標，詳情見下文。 108 | - 智慧指標 (smart pointers)： 智慧指標會在解構時執行清理動作，因此被禁止使用。 請考慮你的使用狀況是否符合這章節中描述的其他模式。 一種簡單的解法是對動態分配的物件使用一般指標，然後永遠不要刪除它 (請看最後一項)。 109 | - 自製型別的靜態變數： 如果你需要對你自己設計的型別使用靜態的常數資料，請確保該型別擁有平凡的解構函式與 `constexpr` 建構函式。 110 | - 如果這些方法都不能用，你可以動態建立一個物件，並永遠都不要刪除它 (例如： `static const auto& impl = *new T(args...);`)。 111 | -------------------------------------------------------------------------------- /src/scoping/namespaces.md: -------------------------------------------------------------------------------- 1 | ## 名稱空間 (Namespaces) 2 | 3 | > 除了某些特殊情況外，程式碼應當放在名稱空間中。 名稱空間應該具有基於專案名稱的獨特名稱，可能也包含其路徑。 不要使用 using 指示詞 (using-directive)，像是 `using namespace foo`。 不要使用行內名稱空間 (inline namespace)。 關於未命名的名稱空間，請參考 「[內部鏈結](internal-linkage.md)」 一節。 4 | 5 | ### 定義 6 | 7 | 名稱空間將全域作用域細分為彼此獨立且具名的子作用域，這可以有效避免在整個作用域中遇到名稱相衝的狀況。 8 | 9 | ### 優點 10 | 11 | 名稱空間提供了一種避免在大型程式中名稱相衝的同時，也能讓大部分程式碼使用較短名稱的方法。 12 | 13 | 例如，兩個不同的專案在全域都具有 `Foo` 這個類別，這個符號可能會在編譯或執行時發生衝突。 如果這些專案能把他們的程式碼分別放在各自的名稱空間下，那麼 `project1::Foo` 跟 `project2::Foo` 就會被視為不同的符號，也不會有衝突的問題，而且在各自的專案中還能夠繼續使用 `Foo` 這個名字同時不需加上前綴。 14 | 15 | 行內名稱空間 (inline namespace) 會自動把它們的名稱放進作用域中。 例如，請參考以下程式碼： 16 | 17 | ```cpp 18 | namespace X { 19 | inline namespace Y { 20 | void foo(); 21 | } // namespace Y 22 | } // namespace X 23 | ``` 24 | 25 | 這會使 `X::Y::foo()` 與 `X::foo()` 可以互相交換使用。 當初行內名稱空間的主要目標就是用來處理不同版本的 ABI (Application Binary Interface, 應用二進位介面) 的兼容問題。 26 | 27 | ### 缺點 28 | 29 | 名稱空間可能容易造成混淆，因為它們將找出一個名稱指向的實際東西這個機制複雜化。 30 | 31 | 行內名稱空間可能會造成混淆，因為名稱實際上不會受限於它們被宣告的名稱空間內。 它們只在某些需要分類不同版本的情況下才可能會有幫助。 32 | 33 | 在某些狀況中，可能會需要持續使用完整的名稱來指出正確的符號。 對於多層的名稱空間來說，這樣的寫法可能會造成雜亂。 34 | 35 | ### 決定 36 | 37 | 名稱空間應該如下列般使用： 38 | 39 | - 遵從 [名稱空間命名](../naming/namespace-names.md) 一章的規則。 40 | - 如同這章節的範例中在名稱空間的收尾處加上註解。 41 | - 名稱空間必須將整個原始碼檔中，在 `#include` 、[gflags](https://gflags.github.io/gflags/) 定義和前向宣告其他名稱空間的類別之後的內容全部包裹起來。 42 | 43 | ```cpp 44 | // 在某個 .h 檔中 45 | namespace mynamespace { 46 | 47 | // 所有的定義都在名稱空間的作用域內 48 | // 注意這裡沒有縮排 49 | class MyClass { 50 | public: 51 | ... 52 | void Foo(); 53 | }; 54 | 55 | } // namespace mynamespace 56 | ``` 57 | 58 | ```cpp 59 | // 在某個 .cc 檔中 60 | namespace mynamespace { 61 | 62 | // 函式的定義也放在名稱空間的作用域內 63 | void MyClass::Foo() { 64 | ... 65 | } 66 | 67 | } // namespace mynamespace 68 | ``` 69 | 70 | 較複雜的 `.cc` 檔可能包含額外細節，例如 flags 或者 using 指示詞。 71 | 72 | ```cpp 73 | #include "a.h" 74 | 75 | ABSL_FLAG(bool, someflag, false, "a flag"); 76 | 77 | namespace mynamespace { 78 | 79 | using ::foo::bar; 80 | 81 | ...code for mynamespace... // 程式碼左側不留空間 82 | 83 | } // namespace mynamespace 84 | ``` 85 | 86 | - 如果想將自動產生的協議訊息 (Protocol Message) 的程式碼放在命名空間中，請在 `.proto` 中使用 `package` 來指定。 詳情請參考 [Protocol Buffer Packages](https://protobuf.dev/reference/cpp/cpp-generated/#package)。 87 | - 別在 `std` 名稱空間下宣告任何東西，包括標準函式庫的前向宣告。 宣告 `std` 名稱空間下的實體可能導致未定義的行為，也就是說，這並不是一個跨平台的作法。 如果想要宣告標準函式庫內的實體，請直接 `#include` 那些標頭檔。 88 | - 你不該為了要讓某個名稱空間中的名稱皆可直接呼叫而使用 「using 指示詞 (using-directive)」。 89 | 90 | ```cpp 91 | // 禁用 -- 這會汙染名稱空間 92 | using namespace foo; 93 | ``` 94 | 95 | - 別在標頭檔中的名稱空間中使用名稱空間別名 (Namespace Alias)，除非是在明確被標示為只給專案內部使用的名稱空間。 因為在一個被載入的標頭檔內的任何東西，都會被當作該檔的公開 API 對待。 96 | 97 | ```cpp 98 | // 在 `.cc` 檔中簡化存取某個常用名稱的動作 99 | namespace fbz = ::foo::bar::baz; 100 | ``` 101 | 102 | ```cpp 103 | // 在 `.h` 檔中簡化存取某個常用名稱的動作 104 | namespace librarian { 105 | namespace internal { // 內部區域，不是公共 API 的一部份 106 | namespace sidetable = ::pipeline_diagnostics::sidetable; 107 | } // namespace internal 108 | 109 | inline void my_inline_function() { 110 | // 只在這個函式（或方法）內才有作用的命名空間別名 111 | namespace baz = ::foo::bar::baz; 112 | ... 113 | } 114 | } // namespace librarian 115 | ``` 116 | 117 | - 別使用行內名稱空間 118 | - 在名稱空間的命名中加入 `internal` 字樣來標註這個名稱空間不該被 API 的使用者所用。 119 | 120 | ```cpp 121 | // 我們不該在非 `absl` 的名稱空間中使用向下面這種內部 API。 122 | using ::absl::container_internal::ImplementationDetail; 123 | ``` 124 | 125 | - 我們推薦在新程式碼中使用單行巢狀名稱空間，但不是必須的。 126 | 127 | ### 譯註四：行內名稱空間介紹 128 | 129 | 因為行內名稱空間並非常見的 C++ 特性，以下稍微介紹一下這個功能。 130 | 131 | 首先看下面這段範例： 132 | 133 | ```cpp 134 | namespace a { 135 | namespace b { 136 | void fun() { 137 | // code 138 | } 139 | } // namespace b 140 | } // namespace a 141 | ``` 142 | 143 | 一般來說，上面這段程式碼想要呼叫 `fun` 這個函式的話，就要使用 `a::b::fun()` 這個名稱。 但是如果此時引入了行內關鍵字，在 `namespace b` 前面加上 `inline`，變成這樣： 144 | 145 | ```cpp 146 | namespace a { 147 | inline namespace b { 148 | void fun() { 149 | // code 150 | } 151 | } // namespace b 152 | } // namespace a 153 | ``` 154 | 155 | 這個時候你使用 `a::fun()` 這個名稱的話，就可以呼叫到 `fun` 這個函式。 當然，使用 `a::b::fun()` 也同樣可以呼叫得到 `fun`。 有興趣的話可以自己試試看。 156 | 157 | 運作的原理很簡單，其實就是程式在編譯將 `a::fun()` 解析成 `a::b::fun()` 而已。 158 | 159 | 那這個技巧有甚麼用？ 既然我想讓其他人直接呼叫到 `fun`，那為什麼還要特別放一個 `namespace b`？ 160 | 161 | 這個技巧最常用到的地方，就像上面 Google 文件中所提到的，版本控管。 162 | 163 | 如果今天我是在寫函式庫，此時我寫了兩種不同版本的 `fun`，可是有些人的程式已經連結到了舊版的 `fun`，那要怎麼樣在不重新編譯那些程式的狀況下保持連結？ 這個時候可以這樣做： 164 | 165 | 假設原本的函式庫長這樣： 166 | 167 | ```cpp 168 | namespace some_lib { 169 | inline namespace v1 { 170 | void fun() { 171 | // code 172 | } 173 | } // namespace v1 174 | } // namespace some_lib 175 | ``` 176 | 177 | 因此原本編譯的程式裡，呼叫到 `some_lib::fun` 的地方都會連結到 `some_lib::v1::fun`。 而此時我只要改成： 178 | 179 | ```cpp 180 | namespace some_lib { 181 | namespace v1 { 182 | void fun() { 183 | // code 184 | } 185 | } // namespace v1 186 | inline namespace v2 { 187 | void fun() { 188 | // code 189 | } 190 | } // namespace v2 191 | } // namespace some_lib 192 | ``` 193 | 194 | 這樣原本連結到 `some_lib::v1::fun` 的程式仍然可以運作，而且新的程式呼叫 `some_lib::fun` 時，也可以如我預期地使用到新的版本 (v2 版)。 因此行內名稱空間才常用於函式庫的版本控管。 但是如同 Google 風格指南所說，這樣的行為可能實在會導致預期外的結果，所以還是盡量避免使用。 195 | --------------------------------------------------------------------------------