Google 開源項目風格指南

原文網址：http://zh-google-styleguide.readthedocs.org/en/latest/google-cpp-styleguide/naming/

其中，藍色字體爲我本身的命名風格，之後看着方便

文件：所有小寫，可包含下劃線；如：my_useful_class;

類型（類、結構體、類型定義typedef、枚舉） ：每一個單詞首字母均大寫；如：MyExcitingClass；

變量/結構體：小寫，可含下劃線；如：my_local_varible;

類成員變量：小寫，可含下劃線，如下劃線結尾；如：my_local_varible_;

函數：第一個單詞小寫，後面每一個單詞首字母大寫；如：addTableEntry();

常量：k開頭，後跟每一個單詞首字母大寫；如：kDaysInAweek;

全局變量： g_開始， 如g_my_exciting;

6. 命名約定

最重要的一致性規則是命名管理. 命名風格快速獲知名字表明是什麼東東: 類型? 變量? 函數? 常量? 宏 ... ? 甚至不須要去查找類型聲明. 咱們大腦中的模式匹配引擎能夠很是可靠的處理這些命名規則.

命名規則具備必定隨意性, 但相比按我的喜愛命名, 一致性更重, 因此無論你怎麼想, 規則總歸是規則.

6.1. 通用命名規則

Tip

函數命名, 變量命名, 文件命名應具有描述性; 不要過分縮寫. 類型和變量應該是名詞, 函數名能夠用 「命令性」 動詞.

如何命名:

儘量給出描述性的名稱. 不要節約行空間, 讓別人很快理解你的代碼更重要. 好的命名風格:

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.

函數名一般是指令性的 (確切的說它們應該是命令), 如 OpenFile(), set_num_errors(). 取值函數是個特例 (在 函數命名 處詳細闡述), 函數名和它要取值的變量同名.

縮寫:

除非該縮寫在其它地方都很是廣泛, 不然不要使用. 例如:

// Good
// These show proper names with no abbreviations. int num_dns_connections; // 大部分人都知道 "DNS" 是啥意思. int price_count_reader; // OK, price count. 有意義. 

Warning

// 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. 

6.2. 文件命名

Tip

文件名要所有小寫, 能夠包含下劃線 (_) 或連字符 (-). 按項目約定來.

可接受的文件命名:

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

C++ 文件要以 .cc 結尾, 頭文件以 .h 結尾.

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

一般應儘可能讓文件名更加明確. http_server_logs.h 就比 logs.h 要好. 定義類時文件名通常成對出現, 如 foo_bar.h 和 foo_bar.cc, 對應於類 FooBar.

內聯函數必須放在 .h 文件中. 若是內聯函數比較短, 就直接放在 .h 中. 若是代碼比較長, 能夠放到以 -inl.h 結尾的文件中. 對於包含大量內聯代碼的類, 可使用三個文件:

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 文件 一節.

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

變量名一概小寫, 單詞之間用下劃線鏈接. 類的成員變量如下劃線結尾, 如:

my_exciting_local_variable
my_exciting_member_variable_ 

普通變量命名:

舉例:

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

Warning

string tableName; // Bad - mixed case. 

結構體變量:

結構體的數據成員能夠和普通變量同樣, 不用像類那樣接下劃線:

struct UrlTableProperties { string name; int num_entries; } 

結構體與類的討論參考 結構體 vs. 類 一節.

全局變量:

對全局變量沒有特別要求, 少用就好, 但若是你要用, 能夠 用 g_ 或其它標誌 做爲前綴, 以便更好的區分局部變量.

6.5. 常量命名

Tip

在名稱前加 k: kDaysInAWeek.

全部編譯時常量, 不管是局部的, 全局的仍是類中的, 和其餘變量稍微區別一下. k 後接大寫字母開頭的單詞::

const int kDaysInAWeek = 7;

6.6. 函數命名

Tip

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

常規函數:

函數名的每一個單詞首字母大寫, 沒有下劃線:（我選擇第一個單詞首字母小寫，以區分類）

AddTableEntry() DeleteUrl() 

取值和設值函數:

取值和設值函數要與存取的變量名匹配. 這兒摘錄一個類, 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_; }; 

其它很是短小的內聯函數名也能夠用小寫字母, 例如. 若是你在循環中調用這樣的函數甚至都不用緩存其返回值, 小寫命名就能夠接受.

6.7. 名字空間命名

Tip

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

關於名字空間的討論和如何命名, 參考 名字空間 一節.

6.8. 枚舉命名

Tip

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

單獨的枚舉值應該優先採用 常量 的命名方式. 但 宏 方式的命名也能夠接受. 枚舉名 UrlTableErrors (以及 AlternateUrlTableErrors) 是類型, 因此要用大小寫混合的方式.

enum UrlTableErrors { kOK = 0, kErrorOutOfMemory, kErrorMalformedInput, }; enum AlternateUrlTableErrors { OK = 0, OUT_OF_MEMORY = 1, MALFORMED_INPUT = 2, }; 

2009 年 1 月以前, 咱們一直建議採用 宏 的方式命名枚舉值. 因爲枚舉值和宏之間的命名衝突, 直接致使了不少問題. 由此, 這裏改成優先選擇常量風格的命名方式. 新代碼應該儘量優先使用常量風格. 可是老代碼不必切換到常量風格, 除非宏風格確實會產生編譯期問題.

6.9. 宏命名

Tip

你並不打算 使用宏, 對吧? 若是你必定要用, 像這樣命名: MY_MACRO_THAT_SCARES_SMALL_CHILDREN.

參考 預處理宏 <preprocessor-macros>; 一般 不該該 使用宏. 若是不得不用, 其命名像枚舉命名同樣所有大寫, 使用下劃線:

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

6.10. 命名規則的特例

Tip

若是你命名的實體與已有 C/C++ 實體類似, 可參考現有命名策略.

bigopen():

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

uint:

typedef

bigpos:

struct 或 class, 參照 pos 的形式

sparse_hash_map:

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

LONGLONG_MAX:

常量, 如同 INT_MAX