Google C++程式設計風格指南（五）：命名約定

http://www.kuqin.com/language/20080722/12016.html

 

1. 總體規則：不要隨意縮寫；2. 巨集、列舉等使用全部大寫+下劃線；3. 變數（含類、結構體成員變數）、檔案、名稱空間、存取函式等使用全部小寫+下劃線，類成員變數以下劃線結尾，全域性變數以g_開頭；4. 參考現有或相近命名約定……

 

• 命名約定

最重要的一致性規則是命名管理，命名風格直接可以直接確定命名實體是：型別、變數、函式、常量、巨集等等，無需查詢實體宣告，我們大腦中的模式匹配引擎依賴於這些命名規則。

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

1. 通用命名規則（General Naming Rules）

函式命名、變數命名、檔案命名應具有描述性，不要過度縮寫，型別和變數應該是名詞，函式名可以用“命令性”動詞。

如何命名：

儘可能給出描述性名稱，不要節約空間，讓別人很快理解你的程式碼更重要，好的命名選擇：

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;  // 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）

檔名要全部小寫，可以包含下劃線（_）或短線（-），按專案約定來。

可接受的檔案命名：

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

C++檔案以.cc結尾，標頭檔案以.h結尾。

不要使用已經存在於/usr/include下的檔名（譯者注，對UNIX、Linux等系統而言），如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檔案一節。

3. 型別命名（Type Names）

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

所有型別命名——類、結構體、型別定義（typedef）、列舉——使用相同約定，例如：

 

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

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

// enums
enum UrlTableErrors { ...

 

4. 變數命名（Variable Names）

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

普通變數命名：

舉例：

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

string tableName;   // Bad - mixed case.

 

 

類資料成員：

結構體的資料成員可以和普通變數一樣，不用像類那樣接下劃線：

struct UrlTableProperties {
  string name;
  int num_entries;
}

 

結構體與類的討論參考第三篇結構體vs.類一節。

全域性變數：

對全域性變數沒有特別要求，少用就好，可以以g_或其他易與區域性變數區分的標誌為字首。

5. 常量命名（Constant Names）

在名稱前加k：kDaysInAWeek。

所有編譯時常量（無論是區域性的、全域性的還是類中的）和其他變數保持些許區別，k後接大寫字母開頭的單詞：

const int kDaysInAWeek = 7;

 

6. 函式命名（Function Names）

普通函式（regular functions，譯者注，這裡與訪問函式等特殊函式相對）大小寫混合，存取函式（accessors and mutators）則要求與變數名匹配：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_;
};

 

其他短小的行內函數名也可以使用小寫字母，例如，在迴圈中呼叫這樣的函式甚至都不需要快取其值，小寫命名就可以接受。

譯者注：從這一點上可以看出，小寫的函式名意味著可以直接內聯使用。

7. 名稱空間（Namespace Names）

名稱空間的名稱是全小寫的，其命名基於專案名稱和目錄結構：google_awesome_project。

關於名稱空間的討論和如何命名，參考第二篇名稱空間。

8. 列舉命名（Enumerator Names）

列舉值應全部大寫，單詞間以下劃線相連：MY_EXCITING_ENUM_VALUE。

列舉名稱屬於型別，因此大小寫混合：UrlTableErrors。

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

 

9. 巨集命名（Macro Names）

你並不打算使用巨集，對吧？如果使用，像這樣：MY_MACRO_THAT_SCARES_SMALL_CHILDREN。

參考第四篇預處理巨集，通常是不使用巨集的，如果絕對要用，其命名像列舉命名一樣全部大寫、使用下劃線：

 

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

 

10. 命名規則例外（Exceptions to Naming Rules）

當命名與現有C/C++實體相似的物件時，可參考現有命名約定：

bigopen()

函式名，參考open()

uint

typedef型別定義

bigpos

struct或class，參考pos

sparse_hash_map

STL相似實體；參考STL命名約定

LONGLONG_MAX

常量，類似INT_MAX

______________________________________

譯者：命名約定就相對輕鬆許多，在遵從程式碼一致性、可讀性的前提下，略顯隨意：

1. 總體規則：不要隨意縮寫，如果說ChangeLocalValue寫作ChgLocVal還有情可原的話，把ModifyPlayerName寫作MdfPlyNm就太過分了，除函式名可適當為動詞外，其他命名儘量使用清晰易懂的名詞；

2. 巨集、列舉等使用全部大寫+下劃線；

3. 變數（含類、結構體成員變數）、檔案、名稱空間、存取函式等使用全部小寫+下劃線，類成員變數以下劃線結尾，全域性變數以g_開頭；

4. 普通函式、型別（含類與結構體、列舉型別）、常量等使用大小寫混合，不含下劃線；

5. 參考現有或相近命名約定。

來自：http://www.cppblog.com/Fox/archive/2008/07/22/56845.html