Google C++ Style Guide

通用命名規則

命名應該要具有敘述的能力;避免使用縮寫。

讓一個名稱具有越清楚的描述越好,包括原因在內。不要去想節省橫向的空間,因為讓你的程式碼能夠被新讀者馬上讀懂這事重要得多。不要使用會讓專案以外的讀者看起來曖昧不明的縮寫,以及不要利用刪除一個單詞之間的字母來製造縮寫。那些可能對專案外但是具有一些相關領域知識的人來說看得懂的縮寫還算可以接受。經驗上來說,一個縮寫如果有被列在維基百科 (Wikipedia) 上的話,應該也可以接受。

int price_count_reader;    // 不含縮寫
int num_errors;            // 「num」是很廣泛運用的慣例
int num_dns_connections;   // 大部份的人都知道「DNS」代表甚麼
int lstm_size;             // 「LSTM」是機器學習 (Machine Learning) 領域中常見的縮寫

注意有些普遍知道的縮寫是可以接受的,像是 i 代表疊代 (iteration) 次數以及 T 代表模板 (template) 參數。

對於某些符號,這份指引建議對應的名稱以大寫字母作為開頭,並在每一個單詞的首字都使用大寫字母 (也就是所謂的駝峰式命名法)。在這種名稱中如果出現縮寫或者首字型縮寫 (acronyms, 譯註:指的是用每個單字的第一個字母組成的縮寫) 的話,偏好將該縮寫或首字型縮寫視為一個單詞來處理 (像是 StartRpc(),而不是 StartRPC())。

模板參數應該要遵從所屬種類的命名風格:型別模板參數應該遵從型別名稱的規則,以及非型別模板參數應該要遵從變數名稱的規則。

檔案名稱

檔案名稱應該完全使用小寫,並可以包含底線 () 或是橫槓 (-)。 關於這點請遵循各專案的慣例。 如果沒有可以遵循且一致的本地模式,偏好使用

一些可接受的檔案名稱範例:

  • my_useful_class.cc
  • my-useful-class.cc
  • myusefulclass.cc
  • myusefulclass_test.cc // _unittest 與 _regtest 兩種寫法都過時了

C++ 檔案應該以 .cc 結尾,同時標頭檔應該以 .h 結尾。 依賴於在某個特定位置被文字引入的檔案應該以 .inc 結尾。

不要使用已經存在於 /usr/include 的檔名,像是 db.h。

一般來說,應該要讓你的檔案名稱非常精確。 例如,使用 http_server_logs.h 而不是 logs.h。 一個常見的狀況是使用相同名稱為一對檔案命名,像是 foo_bar.h 與 foo_bar.cc 定義了名為 FooBar 的類別。

型別名稱

型別名稱始於一個大寫字母,並且每個單字的開頭皆為大寫字母,同時不包含底線:MyExcitingClass、MyExcitingEnum。

所有型別的名稱 - 類別、結構、型別別名、列舉、型別模板參數 - 都有相同的命名慣例。 型別名稱始於一個大寫字母,並且每個單字的開頭皆為大寫字母。 沒有底線。 例如:

// 類別與結構
class UrlTable { ...
class UrlTableTester { ...
struct UrlTableProperties { ...

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

// 使用別名
using PropertiesMap = hash_map<UrlTableProperties *, string>;

// 列舉
enum UrlTableErrors { ...

變數名稱

變數 (包含函式的參數) 與資料成員的名稱全部都使用小寫,並使用底線隔開單字。 類別 (但不包含結構) 的資料成員要另外在尾部加上底線。 例如,區域變數:a_local_variable、結構資料成員:a_struct_data_member、類別資料成員:a_class_datamember

常見的變數名稱

可以接受的:

string table_name;  // 可以 - 使用底線
string tablename;   // 可以 - 全部小寫

不可接受的:

string tableName;   // 不好 - 大小寫混合

類別資料成員

類別資料成員,包括靜態 (static) 與非靜態的,都如同一般變數命名,但要在尾端加上底線。

class TableInfo {
  ...
 private:
  string table_name_;  // 可以 - 尾端有底線
  string tablename_;   // 可以
  static Pool<TableInfo>* pool_;  // 可以
};

結構資料成員

類別資料成員,包括靜態 (static) 與非靜態的,都如同一般變數命名。 他們不像類別一樣要在尾端加上底線。

struct UrlTableProperties {
  string name;
  int num_entries;
  static Pool<UrlTableProperties>* pool;
};

常數名稱

使用 constexpr 或 const 宣告的變數,以及在程式全期數值皆是固定的變數,其名稱應該以「k」為開頭,並使用大小寫混和的寫法。 底線可以用在少數無法使用大小寫明確分開的場合。例如:

const int kDaysInAWeek = 7;
const int kAndroid8_0_0 = 24;  // Android 8.0.0

所有具備以上性質同時有靜態儲存期 (例如靜態變數與全域變數,詳情請參照儲存期) 的變數都應該這樣命名。 這項慣例對其他儲存種類的變數來說是選擇性的 (例如自動變數),其他情況應使用一般的變數命名規則。

函數名稱

一般函式應使用大小寫混和;存取子 (Accessor) 與修改子 (Mutator) 可以使用變數的方式命名。

一般來說,函式應以大寫字母開頭,並在每一個新單字的首字使用大寫字母。

AddTableEntry()
DeleteUrl()
OpenFileOrDie()

(相同的命名規則也適用於類別與名稱空間範圍之中,那些作為 API 的一部分釋出的、或是意圖使人看起來像是函數的常數。 因為這些常數其實是物件而不是函式這點算是不重要的實作細節。)

存取子與修改子 (getset 函式) 可以用變數的方式命名。 他們的命名通常與實際的成員變數有關,但這並非必要。 例如:int count()void set_count(int count)

名稱空間名稱

名稱空間全部使用小寫。 最頂層的名稱空間應使用基於專案名稱的名字。 避免巢狀名稱空間以及與知名頂層名稱空間的命名碰撞。

頂層的命名空間應通常使用專案名稱或者開發該程式的團隊名稱。該名稱空間中的程式碼應該要放在與其名稱空間的命名相符的資料夾中 (或是子資料夾中)

注意針對縮寫名稱的規則也如同變數一樣適用於名稱空間。名稱空間中的程式碼很少會需要提及名稱空間的名稱,所以通常沒有使用縮寫的必要。

避免使用名稱與知名頂層名稱空間衝突的巢狀名稱空間。名稱空間的命名衝突可能因為命名查詢規則造成意外的建置錯誤。特別是不要建立任何命名為 std 的巢狀名稱空間。優先使用獨特的專案 ID (websearch::index、websearch::index_util),而不是容易發生衝突的名稱,像是 websearch::util。

對於 internal 名稱空間,請注意將其他程式碼加入同樣的 internal 名稱空間中會導致衝突 (團隊內部的輔助函式 (Helper Functions) 傾向於且可能導致衝突)。在這種情況下,使用檔名來建立一個獨特的內部名稱很有用 (像是對 frobber.h 中的程式使用 websearch::index::frobber_internal)。

列舉名稱

使用常數命名 : kEnumName

巨集名稱

全部大寫

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

例外

如果你正在為類似於 C 或 C++ 內已經存在的實體進行命名,那麼你可以遵循他們慣例的命名規則。

  • bigopen()
    -- 函式名稱,跟隨 open() 的形式命名
  • uint
    -- typedef
  • bigpos
    -- struct 或 class,跟隨 pos 的形式命名
  • sparse_hash_map
    -- 像是 STL 的實體;跟隨著 STL 的命名慣例
  • LONGLONG_MAX
    -- 一個常數,像 INT_MAX 一樣命名

Struct與Class使用時機

在 c++ 中 struct 與 class 的唯一差別
只是預設為 public 或 private 的不同而已
不過我們還是可以定義coding style

如果你的資料本身就是介面
那麼你可以選擇 struct
或者選擇 class 然後將全部資料宣告為 public
其餘情況下 你應該選擇 class 然後將所有資料都宣告為 private

什麼情況下資料本身就是介面呢?
那就是資料之間有性質相關
但是沒有相依性的時候(也就是不會因為資料錯誤, 就導致整個型別壞掉, 如果會就建議用class 並用interface function包裝變數操作)


如果喜歡文章, 不妨按下喜歡訂閱支持

如果真的想支持我進行創作與實踐計畫, 也可以進行打賞
BTC (BTC) : 1LFRBqvWR9GGizBzoFddkb5xRpAzKRVoDC
BTC (BSC) : 0xe1cda3eb778d1751af17feac796a4bbe4dbca815
BTC (ERC20) : 0xe1cda3eb778d1751af17feac796a4bbe4dbca815
USDT (TRC20) : TT7wgKuYoHwfRy3vCr38Qy3gnS3JJ1aKvn

如果想使用幣安, 可以使用我的推薦連結可以節省手續費10%
或使用推薦碼 : A5YRMD2T


#cpp #struct #C #C語言 #C++ #程式語言 #programing #program language #coding style #命名規則 #class #型態 #類別







Related Posts

MTR04_0703

MTR04_0703

Markdown 常用語法

Markdown 常用語法

Scrum 是什麼及怎麼運用?

Scrum 是什麼及怎麼運用?


Comments