6. 命名約定

最重要的一致性規(guī)則是命名管理. 命名風格快速獲知名字代表是什么東東: 類型? 變量? 函數(shù)? 常量? 宏 ... ? 甚至不需要去查找類型聲明. 我們大腦中的模式匹配引擎可以非常可靠的處理這些命名規(guī)則.

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

6.1. 通用命名規(guī)則

Tip

函數(shù)命名，變量命名，文件命名要有描述性；少用縮寫。

盡可能給有描述性的命名，別心疼空間，畢竟讓代碼易于新讀者理解很重要。不要用只有項目開發(fā)者能理解的縮寫，也不要通過砍掉幾個字母來縮寫單詞。

int price_count_reader;? ? // 無縮寫

int num_errors;? ? ? ? ? ? // “num” 本來就很常見

int num_dns_connections;? ?// 人人都知道 “DNS” 是啥

Warning

int n;? ? ? ? ? ? ? ? ? ? ?// 莫名其妙。

int nerr;? ? ? ? ? ? ? ? ? // 怪縮寫。

int n_comp_conns;? ? ? ? ? // 怪縮寫。

int wgc_connections;? ? ? ?// 只有貴團隊知道是啥意思。

int pc_reader;? ? ? ? ? ? ?// "pc" 有太多可能的解釋了。

int cstmr_id;? ? ? ? ? ? ? // 有刪減若干字母。

6.2. 文件命名

Tip

文件名要全部小寫, 可以包含下劃線 (_) 或連字符 (-). 按項目約定來. 如果并沒有項目約定，”_” 更好。

可接受的文件命名:

* my_useful_class.cc

* my-useful-class.cc

* myusefulclass.cc

* muusefulclass_test.cc // ``_unittest`` 和 ``_regtest`` 已棄用。

C++ 文件要以 .cc 結尾, 頭文件以 .h 結尾. 專門插入文本的文件則以 .inc 結尾，參見:ref:self-contained headers。

不要使用已經存在于 /usr/include 下的文件名 (Yang.Y 注: 即編譯器搜索系統(tǒng)頭文件的路徑), 如db.h.

通常應盡量讓文件名更加明確. http_server_logs.h 就比 logs.h 要好. 定義類時文件名一般成對出現(xiàn), 如 foo_bar.h 和 foo_bar.cc, 對應于類 FooBar.

內聯(lián)函數(shù)必須放在 .h 文件中. 如果內聯(lián)函數(shù)比較短, 就直接放在 .h 中.

6.3. 類型命名

Tip

類型名稱的每個單詞首字母均大寫, 不包含下劃線: MyExcitingClass, MyExcitingEnum.

所有類型命名 —— 類, 結構體, 類型定義 (typedef), 枚舉 —— 均使用相同約定. 例如:

// classes and structs

class UrlTable { ...

class UrlTableTester { ...

struct UrlTableProperties { ...

// typedefs

typedef hash_map<UrlTableProperties *, string> PropertiesMap;

// enums

enum UrlTableErrors { ...

6.4. 變量命名

Tip

變量名一律小寫, 單詞之間用下劃線連接. 類的成員變量以下劃線結尾, 但結構體的就不用，如::a_local_variable, a_struct_data_member, a_class_data_member_.

普通變量命名:

舉例:

string table_name;? // 可 - 用下劃線。

string tablename;? ?// 可 - 全小寫。

Warning

string tableName;? ?// 差 - 混合大小寫。

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

不管是靜態(tài)的還是非靜態(tài)的，類數(shù)據(jù)成員都可以和普通變量一樣, 但要接下劃線。

class TableInfo {

? ...

?private:

? string table_name_;? // 可 - 尾后加下劃線。

? string tablename_;? ?// 可。

? static Pool<TableInfo>* pool_;? // 可。

};

結構體變量:

不管是靜態(tài)的還是非靜態(tài)的，結構體數(shù)據(jù)成員都可以和普通變量一樣, 不用像類那樣接下劃線:

struct UrlTableProperties {

? ? string name;

? ? int num_entries;

}

結構體與類的討論參考 結構體 vs. 類 一節(jié).

全局變量:

對全局變量沒有特別要求, 少用就好, 但如果你要用, 可以用 g_ 或其它標志作為前綴, 以便更好的區(qū)分局部變量.

6.5. 常量命名

Tip

在全局或類里的常量名稱前加 k: kDaysInAWeek. 且除去開頭的 k 之外每個單詞開頭字母均大寫。

所有編譯時常量, 無論是局部的, 全局的還是類中的, 和其他變量稍微區(qū)別一下. k 后接大寫字母開頭的單詞:

const int kDaysInAWeek = 7;

這規(guī)則適用于編譯時的局部作用域常量，不過要按變量規(guī)則來命名也可以。

6.6. 函數(shù)命名

Tip

常規(guī)函數(shù)使用大小寫混合, 取值和設值函數(shù)則要求與變量名匹配: MyExcitingFunction(),MyExcitingMethod(), my_exciting_member_variable(), set_my_exciting_member_variable().

常規(guī)函數(shù):

函數(shù)名的每個單詞首字母大寫, 沒有下劃線。

如果您的某函數(shù)出錯時就要直接 crash, 那么就在函數(shù)名加上 OrDie. 但這函數(shù)本身必須集成在產品代碼里，且平時也可能會出錯。

AddTableEntry()

DeleteUrl()

OpenFileOrDie()

取值和設值函數(shù):

取值（Accessors）和設值（Mutators）函數(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_;

};

其它非常短小的內聯(lián)函數(shù)名也可以用小寫字母, 例如. 如果你在循環(huán)中調用這樣的函數(shù)甚至都不用緩存其返回值, 小寫命名就可以接受.

6.7. 名字空間命名

Tip

名字空間用小寫字母命名, 并基于項目名稱和目錄結構: google_awesome_project.

關于名字空間的討論和如何命名, 參考 名字空間 一節(jié).

6.8. 枚舉命名

Tip

枚舉的命名應當和 常量 或 宏 一致: kEnumName 或是 ENUM_NAME.

單獨的枚舉值應該優(yōu)先采用 常量 的命名方式. 但 宏 方式的命名也可以接受. 枚舉名 UrlTableErrors(以及 AlternateUrlTableErrors) 是類型, 所以要用大小寫混合的方式.

enum UrlTableErrors {

? ? kOK = 0,

? ? kErrorOutOfMemory,

? ? kErrorMalformedInput,

};

enum AlternateUrlTableErrors {

? ? OK = 0,

? ? OUT_OF_MEMORY = 1,

? ? MALFORMED_INPUT = 2,

};

2009 年 1 月之前, 我們一直建議采用 宏 的方式命名枚舉值. 由于枚舉值和宏之間的命名沖突, 直接導致了很多問題. 由此, 這里改為優(yōu)先選擇常量風格的命名方式. 新代碼應該盡可能優(yōu)先使用常量風格. 但是老代碼沒必要切換到常量風格, 除非宏風格確實會產生編譯期問題.

6.9. 宏命名

Tip

你并不打算:ref:使用宏 <preprocessor-macros>, 對吧? 如果你一定要用, 像這樣命名:MY_MACRO_THAT_SCARES_SMALL_CHILDREN.

參考:ref:預處理宏 <preprocessor-macros>; 通常 不應該 使用宏. 如果不得不用, 其命名像枚舉命名一樣全部大寫, 使用下劃線:

#define ROUND(x) ...

#define PI_ROUNDED 3.0

6.10. 命名規(guī)則的特例

Tip

如果你命名的實體與已有 C/C++ 實體相似, 可參考現(xiàn)有命名策略.

bigopen():

函數(shù)名, 參照 open() 的形式

uint:

typedef

bigpos:

struct 或 class, 參照 pos 的形式

sparse_hash_map:

STL 相似實體; 參照 STL 命名約定

LONGLONG_MAX:

常量, 如同 INT_MAX

Google C++命名規(guī)范 - 一雙拖鞋走天下 - 博客園 (cnblogs.com)