花費 3 天時間整理的程式碼規範示例程式碼，你確定不進來看看嗎？
- 2021 年 6 月 26 日
- 筆記
小夥伴們，大家好，小北師兄又來喂飯啦，從上次寫完《關於 Windows 下 Qt 開發，這個問題必須要搞清楚！》後好久沒有更新啦（前段時間出差了好久/(ㄒoㄒ)/~~），最近接手了他人寫的項目，然後按照實際需求小幅度改動程式碼，因此 Qt 學習進度就會減慢了很多，不過師兄一定會在之後學習 Qt 過程中總結一些知識分享給大家。
不知道小夥伴們有沒有接手過他人的項目，反正師兄這次接手這個項目後確實犯難了，沒有一切關於項目的文檔說明，只有一份項目源碼留給我。不過師兄沒有放棄，因為項目要求不是大幅度改動程式碼，師兄還可以閱讀少量源碼來滿足需求。
師兄拿到項目的源碼後就開始粗略看了起來，本來心裡想著程式碼里應該會有一些說明，閱讀起來也能慢慢理解項目，沒想到反手就是一個大大的驚喜：程式碼寫的很隨意，大量的函數可以有幾百行，想看看注釋，結果注釋也是寫的很不規範，看著就像是在學校急忙忙做的程式碼實驗，只有自己能看的懂注釋。
事情的經過就是這樣，面對一個亂糟糟的程式碼，確實提不起來想看的慾望，而且閱讀效率會非常低，也會導致項目的時間線拉長。師兄說了這些，主要是想強調一點：程式碼規範是非常重要的！
一個好的項目，程式碼基本都有統一的規範，否則程式碼就會隨著版本迭代，變得越來越臃腫。程式碼規範應在項目早期建立，這些規範對於保持整個項目的一致性非常有必要，採用一致的規範可以提高效率並簡化項目維護。
一個好的編碼規範，對我們來說能夠起到很多意向不到的效果。至少會有以下好處：
- 提高編碼效率：整齊劃一的程式碼方便進行複製粘貼，復用別人寫好的程式碼很方便，風格也很適配自己的項目
- 提高程式碼的可讀性：看到別人寫的程式碼就和自己寫的沒有什麼差距，這樣就可以使程式設計師很快上手，很好的理解軟體，進而降低軟體的維護成本
- 方便團隊協同工作：大家使用同一的規範，這樣就消除了五花八分的書寫方式，統一協調。
說了這麼多關於程式碼規範的重要性，師兄建議大家去看看 Google 的關於 C++ 的程式碼規範（當然 Google 還有其他程式語言的規範，文章底部會有鏈接），這份規範指南的價值不僅僅局限於它羅列出的規範， 更具參考意義的是它為了列出規範而做的謹慎權衡過程，大家可以從中學到很多知識。
這份規範指南不僅列出你要怎麼做， 還告訴你為什麼要這麼做,，哪些情況下可以不這麼做，以及如何權衡其利弊我們在自己平時開發程式時，可以參照該指南及從中汲取靈感， 建立適合自身實際情況的規範。
通過閱讀這份規範指南，師兄做了一份筆記，其中包括文字版記錄和程式碼版記錄，文字版主要是師兄看這份指南時寫的筆記，程式碼版記錄是師兄根據這份指南，用程式碼的形式重新描繪了這份指南
如果小夥伴們覺得文字版不好記憶，可以在寫程式碼時打開我這份示例程式碼找到相關的例子來參考，下面附錄部分貼上了示例 .h 文件的程式碼，大家可以看看。最後我在百度網盤中也保存了這份程式碼示例和文字版筆記，可以在後台回復 「code_style」 關鍵字獲取網盤鏈接。當然也可以來我的 Github 上進行下載。
/*
* CopyRight (c) 2021 saber
* File: example.cc
* Project: code_style
* Author: gcj
* Date: 2021/6/19
* Description: google code style
* License: see the LICENSE.txt file
* github: //github.com/saber/code_style
*/
// 說明當前文件函數功能和使用，個人覺得太麻煩的說明可以省略！只需要簡答介紹和提示。或者也可以不寫！
// 行的長度最好不要超過 80！
// 頭文件包含按照 <PROJECT>_<PATH>_<FILE>_H_ 進行命名，項目 code_style 路徑為 code_style/example.h 可寫成：
#ifndef CODE_STYLE_EXAMPLE_H_
#define CODE_STYLE_EXAMPLE_H_
**留白**
// 頭文件包含順序：相關頭文件（項目中的）、C 庫、C++庫、其他庫.h,比如第三方 opencv、Eigen 等等庫
#include <sys/types.h> // C 庫頭文件
#include <vector> // C++ 頭文件
#include <Eigen/Core>
#include <opencv2/core/core.hpp> // 其他第三方庫
#include "code_style/xxxx.h" // 利用項目內其他頭文件的某個類型或函數，不要使用 .. 類似的相對路徑，要使用相對於項目根目錄路徑
// 通用命名規則：函數、變數、文件、應具有描述性，不要過度縮寫，類型和變數名應該是名詞，函數名可以用「命令性」動詞
// 常量和靜態存儲期變數命名：名稱前面加k，例如 kDaysInAWeek，
// 所有具有靜態存儲類型的變數 (例如靜態變數或全局變數) 都應當以此方式命名。
// 綜合來說：就是所有 const /constexpr 變數（局部或全局，類內），
// 以及 靜態存儲期變數（包括 static 標識的變數或者未命名的命名空間）的都要用 k 開頭！！！！
extern int kGlobalVar; // 需要在頭文件中進行外部聲明
extern constexpr int kGGG1;
extern const int kGlobalVar2;
extern int kGoogleStatic1 = 4; // 這裡去掉了 static
// 這裡可以放置外部前置類全局函數的聲明，然後在 .cc 文件中進行包含，如果本頭文件一些函數和成員函數定義中使用
// 了這個類對象，那麼也需要在頭文件中添加 #include "ABC" #include "DEF"
class ABC;
template <typename T>
class DEF;
// 可以在 .cc文件、 .h文件的函數、方法或類中，可以使用 using 聲明即 using std::string
namespace xxxx項目名稱 { // 小寫字母，最高級命名空間取決於項目名稱，不要使用縮寫，但是大家都知道的縮寫可以用。
namespace code_style { // 對應於 項目/code_style 文件夾
// 可以在這裡加上 別名
using Uint8Color = std::array<uint8, 3>;
// TODO 對臨時的，短期的解決方案，但不完美的程式碼使用這個注釋，或者寫一些 "將來某一天要做的事情"即 未完成事。或明確的事項
// DEPRECATED 棄用注釋，不是強制棄用，格式如下：
// DEPRECATED(寫說明，幫助其他人修復其調用點) ，或者一般做法，可以將一個棄用函數改造成為一個內聯函數，這一函數將調用新的介面。
void FuncTodo() {
// pass
}
// 改造後的內聯函數（內聯函數放在頭文件！）
inline FuncTodo() {
// pass
// 調用新的介面
FuncOne();
}
// 函數調用時，儘可能易讀性：比如： my_widget.Transform(x1, x2, x3, y1, y2, y3, y4, z1, z2, z3);可以改為：
// my_widget.Transform(x1, x2, x3,
// y1, y2, y3,
// z1, z2, z3);
// 屬性和展開為屬性的宏，寫在函數聲明或定義的最前面，即返回類型之前
// 宏的名字，注意全大寫，然後下劃線鏈接。
#define MUST_USE_RESULT // 起到提示作用，可以想著用
// 函數聲明：注釋函數功能，標註： 對於比較明顯的就不需要說明了。
// 輸入輸出，
// 函數是否分配了必須由調用者釋放的空間。
// 參數是否可以為空指針，或者在函數內部進行空指針檢測，提示錯誤！用 glog CHECK（）宏。
void GoogleTest(); // 盡量使用這種在命名空間中的函數，不要在命名空間外部定義全局函數，而 static 函數要用在類中
// 類型名稱的每個單詞首字母均大寫, 不包含下劃線
using VectorInt = std::vector<int>;
typedef std::vector<int> VectorInt;
// 內部變數命名規則與普通變數命名規則一致，小寫加下劃線鏈接，但是不需要結尾加下劃線，恰好區分 class
struct GoogleSection {
int data_member; // 變數：不需要下劃線結尾，當做普通變數處理，小寫字母加下劃線
int data_2;
static int kStructTest; // 用 k 開頭
const int kData = 3;
};
// 列表初始化
GoogleSection cc{2,3};
// 函數程式碼比較少 10 行的函數聲明為內聯函數，且聲明和定義都放在頭文件中，否則編譯失敗。
// 對於包含 for()等循環 switch 的情況，最好不要用內聯，除非，for()等循環 switch 用的少，或基本很少執行。
// 當然對於有些雖然聲明為內聯，但是編譯器有時不會看做內聯。比如遞歸函數、虛函數
inline void TestInline(int test_num) {
int test_num_buf = test_num + 2;
return; // 建議 void 返回格式
}
// 類注釋：在類前面，描述類的功能
// 和用法，比如 Example:...寫下簡單用法
// 除非它的功能相當明顯。一般情況下可以不說明，用分行 // 注釋法
// 是否可多執行緒訪問實例，需要說明，以及可重入性！
// TODO: 進行一些還需要做的事情！
class GoogleNorm { // 對應文件名字 google_norm.h google_norm.cc
public: // 公有類型聲明
typedef int int32;
typedef long long int64;
enum GoogleChoice { GLOG_CHOICE, GFLAGS_CHOICE }; // 枚舉值，採用常量的命名方式。
/*
enum GoogleChoice {
GLOG_CHOICE,
GFLAGS_CHOICE
}; // 枚舉值，採用常量的命名方式。
*/
// 內部變數命名規則與普通變數命名規則一致，小寫加下劃線鏈接，但是不需要結尾加下劃線，恰好區分 class
struct GoogleSection {
int data_member; // 變數：不需要下劃線結尾，當做普通變數處理，小寫字母加下劃線
int data_2;
static int kStructTest; // 用 k 開頭
const int kData = 3;
};
private: // 私有類型聲明
// 嵌套類前置聲明（之後在 .cc 文件中進行定義即可）
// 如果這個類不對外開放，那麼就在在對應的 .cc 文件中進行定義，
// 否則就在該頭文件中進行定義且改為 public 訪問許可權
class NestClass;
public: // 外部調用的函數及變數
// 屬於 static const constexpr 的數據成員要放在 public 後面，剩下其他變數全部是 private
constexpr static const char* kConfigurationFileActionName = // k 開頭 // 因為是 static 常量
"intensity_to_color";
static const kMemberStaticConst = 3;
GoogleNorm() = default;
// 構造函數一般不注釋，切記，讀程式碼的人知道構造/析構函數的功能，需要註明函數對參數做了什麼，是否取得指針所有權，析構清理了什麼
GoogleNorm(int i ) {}
GoogleNorm(const GoogleNorm &other) : section_cout_(other.section_cout_) {
int * temp = new (nothrow) int[other.ClassStatic]();
// 拷貝元素
temp
}
~GoogleNorm() = default;
//or
// 析構函數，注意釋放記憶體，以及變數對齊問題，顯示整齊
~GoogleNorm() {
if (nullptr != queue_) {
delete[] queue_;
queue_ = nullptr;
capacity_ = 0;
size_ = 0;
head_ = 0;
tail_ = 0;
}
}
// 屬性宏或展開為屬性的宏，寫在函數聲明或定義的最前面。 表示提醒調用者
MUST_USE_RESULT bool IsOk();
void get_const(){ return ClassStatic_; } // 單函數內部要留白左右一個空格
void get_section() const { return section_cout_; } // 取值函數和設值函數要全小寫加下劃線。最好與實際成員變數對應
// 聲明：注釋函數功能：對於明顯的可以不用說明。比如上面取值和設值函數就不用加註釋
// 輸入輸出，
// 函數是否分配了必須由調用者釋放的空間。
// 參數是否可以為空指針，或者在函數內部進行空指針檢測，提示錯誤！用 glog CHECK（）宏。
void MemberFunc(); // 普通函數 單詞首字母大寫！
protected:
private: // 類成員變數要加下劃線，一律小寫字母加下劃線，結尾加下劃線
static int kClassStatic = 3;
const int kDaysInWeek_ = 8;
// 空格前置 風格一致
char *c; // char &c;
// 數據成員注釋，一般不用，但是對於變數可以接受 NULL or -1 這種值時，需要注釋代表的含義
int section_cout_; // 類的成員 變數（靜態、非靜態），下劃線結尾
int *p_; // 一段記憶體
};
} // namespace code_style
} // namespace xxxx項目名稱
**留白一行**
#endif // CODE_STYLE_EXAMPLE_H_
參考資料
歡迎大家關注我的微信公眾號「小北師兄」，好的文章會優先在裡面不定期分享！
比如：
「反覆研究好幾遍，我才發現關於 CMake 變數還可以這樣理解！」
打開微信客戶端，掃描下方二維碼即可關注！
