花费 3 天时间整理的代码规范示例代码，你确定不进来看看吗？

小伙伴们，大家好，小北师兄又来喂饭啦，从上次写完《关于 Windows 下 Qt 开发，这个问题必须要搞清楚！》后好久没有更新啦（前段时间出差了好久/(ㄒoㄒ)/~~），最近接手了他人写的项目，然后按照实际需求小幅度改动代码，因此 Qt 学习进度就会减慢了很多，不过师兄一定会在之后学习 Qt 过程中总结一些知识分享给大家。

不知道小伙伴们有没有接手过他人的项目，反正师兄这次接手这个项目后确实犯难了，没有一切关于项目的文档说明，只有一份项目源码留给我。不过师兄没有放弃，因为项目要求不是大幅度改动代码，师兄还可以阅读少量源码来满足需求。

师兄拿到项目的源码后就开始粗略看了起来，本来心里想着代码里应该会有一些说明，阅读起来也能慢慢理解项目，没想到反手就是一个大大的惊喜：代码写的很随意，大量的函数可以有几百行，想看看注释，结果注释也是写的很不规范，看着就像是在学校急忙忙做的代码实验，只有自己能看的懂注释。

事情的经过就是这样，面对一个乱糟糟的代码，确实提不起来想看的欲望，而且阅读效率会非常低，也会导致项目的时间线拉长。师兄说了这些，主要是想强调一点：代码规范是非常重要的！

一个好的项目，代码基本都有统一的规范，否则代码就会随着版本迭代，变得越来越臃肿。代码规范应在项目早期建立，这些规范对于保持整个项目的一致性非常有必要，采用一致的规范可以提高效率并简化项目维护。

一个好的编码规范，对我们来说能够起到很多意向不到的效果。至少会有以下好处：

1. 提高编码效率：整齐划一的代码方便进行复制粘贴，复用别人写好的代码很方便，风格也很适配自己的项目
2. 提高代码的可读性：看到别人写的代码就和自己写的没有什么差距，这样就可以使程序员很快上手，很好的理解软件，进而降低软件的维护成本
3. 方便团队协同工作：大家使用同一的规范，这样就消除了五花八分的书写方式，统一协调。

说了这么多关于代码规范的重要性，师兄建议大家去看看 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: https://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_

参考资料

C++ 风格指南

Google 开源项目风格指南 (中文版)

欢迎大家关注我的微信公众号「小北师兄」，好的文章会优先在里面不定期分享！
比如：
「反复研究好几遍，我才发现关于 CMake 变量还可以这样理解！」

打开微信客户端，扫描下方二维码即可关注！