命名約定

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

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

通用命名規(guī)則

Tip
    函數(shù)命名, 變量命名, 文件命名應(yīng)具備描述性; 不要過度縮寫. 類型和變量應(yīng)該是名詞, 函數(shù)名可以用 "命令性" 動(dòng)詞.

如何命名: 盡可能給出描述性的名稱. 不要節(jié)約行空間, 讓別人很快理解你的代碼更重要. 好的命名風(fēng)格:

            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ù)名通常是指令性的 (確切的說它們應(yīng)該是命令), 如 OpenFile(), set_num_errors(). 取值函數(shù)是個(gè)特例 (在 :ref:函數(shù)命名 <function-names> 處詳細(xì)闡述), 函數(shù)名和它要取值的變量同名.

縮寫: 除非該縮寫在其它地方都非常普遍, 否則不要使用. 例如:

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

永遠(yuǎn)不要用省略字母的縮寫:

            int error_count;  // Good.
            int error_cnt;    // Bad.

文件命名

Tip
    文件名要全部小寫, 可以包含下劃線 (``_``) 或連字符 (``-``). 按項(xiàng)目約定來.

可接受的文件命名::

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

C++ 文件要以 .cc 結(jié)尾, 頭文件以 .h 結(jié)尾.

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

通常應(yīng)盡量讓文件名更加明確. 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.

參考 :ref:-inl.h 文件 <inl-files> 一節(jié).

類型命名

Tip
    類型名稱的每個(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 { ...

變量命名

Tip
    變量名一律小寫, 單詞之間用下劃線連接. 類的成員變量以下劃線結(jié)尾, 如::

        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.

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

            struct UrlTableProperties {
                string name;
                int num_entries;
            }

結(jié)構(gòu)體與類的討論參考 :ref:結(jié)構(gòu)體 vs. 類 <structs_vs_classes> 一節(jié).

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

常量命名

Tip
    在名稱前加 ``k``: kDaysInAWeek.

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

函數(shù)命名

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

常規(guī)函數(shù):
    函數(shù)名的每個(gè)單詞首字母大寫, 沒有下劃線::

    AddTableEntry()
    DeleteUrl()

取值和設(shè)值函數(shù):
    取值和設(shè)值函數(shù)要與存取的變量名匹配. 這兒摘錄一個(gè)類, ``num_entries_`` 是該類的實(shí)例變量:

        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ù)甚至都不用緩存其返回值, 小寫命名就可以接受.

## 名字空間命名

Tip 名字空間用小寫字母命名, 并基于項(xiàng)目名稱和目錄結(jié)構(gòu): google_awesome_project.

關(guān)于名字空間的討論和如何命名, 參考 :ref:`名字空間 <namespaces>` 一節(jié).

## 枚舉命名

Tip 枚舉的命名應(yīng)當(dāng)和 :ref:常量 <constant-names> 或 :ref:宏 <macro-names> 一致: kEnumName 或是 ENUM_NAME.

單獨(dú)的枚舉值應(yīng)該優(yōu)先采用 :ref:`常量 <constant-names>` 的命名方式. 但 :ref:`宏 <macro-names>` 方式的命名也可以接受. 枚舉名 ``UrlTableErrors`` (以及 ``AlternateUrlTableErrors``) 是類型, 所以要用大小寫混合的方式.

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

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

## 宏命名

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

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

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

## 命名規(guī)則的特例

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

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

``uint``:
    ``typedef``

``bigpos``:
    ``struct`` 或 ``class``, 參照 ``pos`` 的形式

``sparse_hash_map``:
    STL 相似實(shí)體; 參照 STL 命名約定

``LONGLONG_MAX``:
    常量, 如同 ``INT_MAX``