13条大型C++项目编码规范：从命名到架构 | 最佳实践

13条大型C++项目编码规范：从命名到架构 #

前言 #

在大型项目中，代码规范非常重要。特别是同一个团队，同一个项目，一定要有严格的编码规范，团队所有开发人员统一使用同一套编码规范为准则进行开发。它不仅能够保证代码的可读性和可维护性，还能提高开发效率，减少错误的发生。

本文会列举出我自己平时编码过程中总结下来的 13 条编码必需的规范，分享出来。

细则 #

1. 命名规范 #

变量、函数、类名等应具有描述性，定义一定要有意义，便于开发者理解具体用途，提高代码的可读性。也要避免使用魔法数字，尽量使用可以明确表达具体含义的枚举或常量代替。

// 不好的命名
int x = 10;

// 好的命名
int maxIterations = 10;

2. 使用恰当的数据类型 #

不正确的数据类型可能导致内存浪费或错误的数据操作。例如，使用常量来表示不变的值。使用无符号整数来表示数量和索引，要不为什么标准库的 size 类型都是 size_t 呢？

3. 保持代码简洁 #

我们需要保持函数和方法尽可能地短小精悍。长函数往往难以理解和维护，而且容易隐藏错误。避免使用复杂的语句和过多的嵌套，复杂和嵌套过深的代码会导致理解困难和维护难度增加。建议巧用工具，有工具可以检测代码语句的复杂度。

// 不好的代码风格
if (x > 5) {
    if (y < 10) {
        // ...
    }
} else {
    // ...
}

// 好的代码风格
if (x > 5 && y < 10) {
    // ...
} else {
    // ...
}

4. 错误处理 #

应该合理处理错误情况，并提供有用的错误信息。忽视错误处理可能导致程序崩溃或不可预见的行为。（这里也要有个度，有些开发同学的想法是尽可能兜住所有错误，一定要确保程序不发生 crash。我倒认为，有些异常情况如果无法有效处理的话就没必要兜住（比如捕获某些信号），应该让它 crash，如果放任它继续运行的话，可能会出现奇奇怪怪的难以排查的逻辑错误，到时候更麻烦。）

// 好的错误处理。最好是使用异常处理机制，而不是错误码方式
try {
    // ...
} catch (const std::exception& e) {
    std::cerr << "Error: " << e.what() << std::endl;
}

5. 资源管理 #

确保及时释放不再使用的资源，如动态分配的内存或打开的文件句柄。不释放资源可能导致内存泄漏或其他资源浪费。具体方案应该避免使用裸指针，尽可能使用智能指针，比如 unique_ptr 或者 shared_ptr。

6. 封装 #

将相关的功能封装到类或函数中，并通过方法来访问，避免全局变量和裸奔的代码。全局变量使得代码更难理解，因为它们可以在任何地方被修改，且有很多坑。没有良好的封装可能导致代码重复和难以维护。比如一个函数两千行，那谁看你的代码不都得大呼一声：xxx。

// 好的封装
class MyClass {
public:
    int GetData() const { return data_; }
private:
    int data_;
};

7. 文件组织规范 #

合理组织文件和目录结构，使得代码易于查找和维护。不合理的文件组织可能导致项目结构混乱和编译效率低下。非必要的头文件，不要 include，开发时要想清楚，需要暴露什么，不需要暴露什么，不需要暴露的细节，使用 pimpl 模式隐藏。

// 好的封装
class MyClass {
public:
    int GetData() const { return data_; }
private:
    int data_;
};

8. 测试规范 #

一定要有单元测试，同时，测试先行。编写测试用例来验证代码的正确性和稳定性。缺乏测试可能导致潜在的错误和漏洞。

// 好的继承
class Base {
public:
    virtual ~Base();
    virtual void print() { /*...*/ }
};

class Derived : public Base {
public:
    void print() override { /*...*/ }
};

9. 谨慎使用宏 #

因为它们可能导致意想不到且难以调试的编译或者逻辑错误。

// 好的文件组织
/myproject/src/main.cpp
/myproject/include/MyClass.h
/myproject/tests/testMyClass.cpp

// 不好的文件组织
/myproject/main.cpp
/myproject/MyClass.h
/myproject/testMyClass.cpp

10. 在可能的情况下，优先使用标准库 #

标准库提供了许多经过良好测试的功能，可以减少错误的可能性。如果需要引入三方库，尽量选择 star 数量多，使用人数较多的三方库，并搭配完备的测试流程。

// 好的测试示例
void testMyFunction() {
    assert(myFunction(1, 2) == 3);
}

11. 多线程编程 #

正确使用多线程机制来并行执行任务。确保线程安全性，并避免竞争条件和其他并发相关的问题。使用 join 方式管理线程，禁止使用 detach。优先使用消息队列形式传递消息，而非共享变量等手段。

12. 代码复用 #

尽量复用已有的代码模块和库，而不是重新编写相同的功能，Dont repeat yourself。

13. 格式化 #

提交到远端仓库的代码一定要格式化，且团队使用统一的格式化风格，可以在 MR 的时候做一次检测拦截，如果检测到代码没有格式化，强制不允许被合入。

总结 #

本期无总结。

思考 #

  1. 你觉得还有哪些编码规范是一定要遵守的？

参考资料 https://zh-google-styleguide.readthedocs.io/en/latest/google-cpp-styleguide/contents.html

© 2025 C++ 编程指南 | 沪ICP备2023022925号-2