游戲人生

原文地址：Google C++ Style Guide

• 命名約定

最重要的一致性規(guī)則是命名管理，命名風(fēng)格直接可以直接確定命名實(shí)體是：類型、變量、函數(shù)、常量、宏等等，無需查找實(shí)體聲明，我們大腦中的模式匹配引擎依賴于這些命名規(guī)則。

命名規(guī)則具有一定隨意性，但相比按個(gè)人喜好命名，一致性更重要，所以不管你怎么想，規(guī)則總歸是規(guī)則。

1. 通用命名規(guī)則（General Naming Rules）

函數(shù)命名、變量命名、文件命名應(yīng)具有描述性，不要過度縮寫，類型和變量應(yīng)該是名詞，函數(shù)名可以用“命令性”動(dòng)詞。

如何命名：

盡可能給出描述性名稱，不要節(jié)約空間，讓別人很快理解你的代碼更重要，好的命名選擇：

int num_errors;                  // Good.
int num_completed_connections;   // Good.

丑陋的命名使用模糊的縮寫或隨意的字符：

int n;                           // Bad - meaningless.
int nerr;                        // Bad - ambiguous abbreviation.
int n_comp_conns;                // Bad - ambiguous abbreviation.

類型和變量名一般為名詞：如FileOpener、num_errors。

函數(shù)名通常是指令性的，如OpenFile()、set_num_errors()，訪問函數(shù)需要描述的更細(xì)致，要與其訪問的變量相吻合。

縮寫：

除非放到項(xiàng)目外也非常明了，否則不要使用縮寫，例如：

// Good
// These show proper names with no abbreviations.
int num_dns_connections;  // Most people know what "DNS" stands for.
int price_count_reader;   // OK, price count. Makes sense.

// Bad!
// Abbreviations can be confusing or ambiguous outside a small group.
int wgc_connections;  // Only your group knows what this stands for.
int pc_reader;        // Lots of things can be abbreviated "pc".

不要用省略字母的縮寫：

int error_count;  // Good.

int error_cnt;    // Bad.

2. 文件命名（File Names）

文件名要全部小寫，可以包含下劃線（_）或短線（-），按項(xiàng)目約定來。

可接受的文件命名：

my_useful_class.cc
my-useful-class.cc
myusefulclass.cc

C++文件以.cc結(jié)尾，頭文件以.h結(jié)尾。

不要使用已經(jīng)存在于/usr/include下的文件名（譯者注，對(duì)UNIX、Linux等系統(tǒng)而言），如db.h。

通常，盡量讓文件名更加明確，http_server_logs.h就比logs.h要好，定義類時(shí)文件名一般成對(duì)出現(xiàn)，如foo_bar.h和foo_bar.cc，對(duì)應(yīng)類FooBar。

內(nèi)聯(lián)函數(shù)必須放在.h文件中，如果內(nèi)聯(lián)函數(shù)比較短，就直接放在.h中。如果代碼比較長(zhǎng)，可以放到以-inl.h結(jié)尾的文件中。對(duì)于包含大量?jī)?nèi)聯(lián)代碼的類，可以有三個(gè)文件：

url_table.h      // The class declaration.
url_table.cc     // The class definition.
url_table-inl.h  // Inline functions that include lots of code.

參考第一篇-inl.h文件一節(jié)。

3. 類型命名（Type Names）

類型命名每個(gè)單詞以大寫字母開頭，不包含下劃線：MyExcitingClass、MyExcitingEnum。

所有類型命名——類、結(jié)構(gòu)體、類型定義（typedef）、枚舉——使用相同約定，例如：

// classes and structs
class UrlTable { ... 
class UrlTableTester { ... 
struct UrlTableProperties { ...

// typedefs
typedef hash_map<UrlTableProperties *, string> PropertiesMap;

// enums
enum UrlTableErrors { ...

4. 變量命名（Variable Names）

變量名一律小寫，單詞間以下劃線相連，類的成員變量以下劃線結(jié)尾，如my_exciting_local_variable、my_exciting_member_variable_。

普通變量命名：

舉例：

string table_name;  // OK - uses underscore.
string tablename;   // OK - all lowercase.

string tableName;   // Bad - mixed case.

類數(shù)據(jù)成員：

結(jié)構(gòu)體的數(shù)據(jù)成員可以和普通變量一樣，不用像類那樣接下劃線：

struct UrlTableProperties {
  string name;
  int num_entries;
}

結(jié)構(gòu)體與類的討論參考第三篇結(jié)構(gòu)體vs.類一節(jié)。

全局變量：

對(duì)全局變量沒有特別要求，少用就好，可以以g_或其他易與局部變量區(qū)分的標(biāo)志為前綴。

5. 常量命名（Constant Names）

在名稱前加k：kDaysInAWeek。

所有編譯時(shí)常量（無論是局部的、全局的還是類中的）和其他變量保持些許區(qū)別，k后接大寫字母開頭的單詞：

const int kDaysInAWeek = 7;

6. 函數(shù)命名（Function Names）

普通函數(shù)（regular functions，譯者注，這里與訪問函數(shù)等特殊函數(shù)相對(duì)）大小寫混合，存取函數(shù)（accessors and mutators）則要求與變量名匹配：MyExcitingFunction()、MyExcitingMethod()、my_exciting_member_variable()、set_my_exciting_member_variable()。

普通函數(shù)：

函數(shù)名以大寫字母開頭，每個(gè)單詞首字母大寫，沒有下劃線：

AddTableEntry()
DeleteUrl()

存取函數(shù)：

存取函數(shù)要與存取的變量名匹配，這兒摘錄一個(gè)擁有實(shí)例變量num_entries_的類：

class MyClass {
 public:
  ...
  int num_entries() const { return num_entries_; }
  void set_num_entries(int num_entries) { num_entries_ = num_entries; }

 private:
  int num_entries_;
};

其他短小的內(nèi)聯(lián)函數(shù)名也可以使用小寫字母，例如，在循環(huán)中調(diào)用這樣的函數(shù)甚至都不需要緩存其值，小寫命名就可以接受。

譯者注：從這一點(diǎn)上可以看出，小寫的函數(shù)名意味著可以直接內(nèi)聯(lián)使用。

7. 命名空間（Namespace Names）

命名空間的名稱是全小寫的，其命名基于項(xiàng)目名稱和目錄結(jié)構(gòu)：google_awesome_project。

關(guān)于命名空間的討論和如何命名，參考第二篇命名空間。

8. 枚舉命名（Enumerator Names）

枚舉值應(yīng)全部大寫，單詞間以下劃線相連：MY_EXCITING_ENUM_VALUE。

枚舉名稱屬于類型，因此大小寫混合：UrlTableErrors。

enum UrlTableErrors {
  OK = 0,
  ERROR_OUT_OF_MEMORY,
  ERROR_MALFORMED_INPUT,
};

9. 宏命名（Macro Names）

你并不打算使用宏，對(duì)吧？如果使用，像這樣：MY_MACRO_THAT_SCARES_SMALL_CHILDREN。

參考第四篇預(yù)處理宏，通常是不使用宏的，如果絕對(duì)要用，其命名像枚舉命名一樣全部大寫、使用下劃線：

#define ROUND(x) ...
#define PI_ROUNDED 3.0
MY_EXCITING_ENUM_VALUE

10. 命名規(guī)則例外（Exceptions to Naming Rules）

當(dāng)命名與現(xiàn)有C/C++實(shí)體相似的對(duì)象時(shí)，可參考現(xiàn)有命名約定：

bigopen()

函數(shù)名，參考open()

uint

typedef類型定義

bigpos

struct或class，參考pos

sparse_hash_map

STL相似實(shí)體；參考STL命名約定

LONGLONG_MAX

常量，類似INT_MAX

______________________________________

譯者：命名約定就相對(duì)輕松許多，在遵從代碼一致性、可讀性的前提下，略顯隨意：

1. 總體規(guī)則：不要隨意縮寫，如果說ChangeLocalValue寫作ChgLocVal還有情可原的話，把ModifyPlayerName寫作MdfPlyNm就太過分了，除函數(shù)名可適當(dāng)為動(dòng)詞外，其他命名盡量使用清晰易懂的名詞；

2. 宏、枚舉等使用全部大寫+下劃線；

3. 變量（含類、結(jié)構(gòu)體成員變量）、文件、命名空間、存取函數(shù)等使用全部小寫+下劃線，類成員變量以下劃線結(jié)尾，全局變量以g_開頭；

4. 普通函數(shù)、類型（含類與結(jié)構(gòu)體、枚舉類型）、常量等使用大小寫混合，不含下劃線；

5. 參考現(xiàn)有或相近命名約定。