/cpp-coding-standards

name: cpp-coding-standards
description: 基于 C++ 核心指南 (isocpp.github.io) 的 C++ 编码规范。在编写、评审或重构 C++ 代码时使用，以强制执行现代、安全且地道的实践。
origin: ECC

C++ 编码规范 (C++ Core Guidelines)

源自 [C++ 核心指南 (C++ Core Guidelines)](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) 的现代 C++ (C++17/20/23) 综合编码规范。强制执行类型安全 (Type safety)、资源安全 (Resource safety)、不变性 (Immutability) 和清晰度。

何时使用

• 编写新的 C++ 代码（类、函数、模板）
• 评审或重构现有的 C++ 代码
• 在 C++ 项目中做出架构决策
• 在 C++ 代码库中强制执行一致的风格
• 在语言特性之间进行选择（例如 `enum` vs `enum class`，原始指针 vs 智能指针）

何时不使用

• 非 C++ 项目
• 无法采用现代 C++ 特性的遗留 C 代码库
• 特定指南与硬件约束冲突的嵌入式/裸机上下文（需选择性调整）

核心原则 (Cross-Cutting Principles)

以下主题贯穿整个指南并构成基础：

1. **处处 RAII** (P.8, R.1, E.6, CP.20)：将资源生命周期与对象生命周期绑定。资源获取即初始化 (RAII) 2. **默认不变性** (P.10, Con.1-5, ES.25)：优先使用 `const`/`constexpr`；可变性应当是例外。不变性 (Immutability) 3. **类型安全** (P.4, I.4, ES.46-49, Enum.3)：利用类型系统在编译时防止错误。类型安全 (Type safety) 4. **表达意图** (P.3, F.1, NL.1-2, T.10)：名称、类型和概念应能传达目的。表达意图 (Express intent) 5. **最小化复杂性** (F.2-3, ES.5, Per.4-5)：简单的代码才是正确的代码 6. **值语义优于指针语义** (C.10, R.3-5, F.20, CP.31)：优先考虑按值返回和作用域对象。值语义 (Value semantics)

哲学与接口 (P.*, I.*)

核心规则

| 规则 | 摘要 | |------|---------| | **P.1** | 直接在代码中表达思想 | | **P.3** | 表达意图 | | **P.4** | 理想情况下，程序应该是静态类型安全的 | | **P.5** | 优先考虑编译时检查而非运行时检查 | | **P.8** | 不要泄露任何资源 | | **P.10** | 优先考虑不可变数据而非可变数据 | | **I.1** | 使接口显式化 | | **I.2** | 避免使用非 const 的全局变量 | | **I.4** | 使接口具有精确且强类型的定义 | | **I.11** | 绝不通过原始指针或引用转移所有权 | | **I.23** | 保持较少的函数参数数量 |

正确示例 (DO)

// P.10 + I.4: 不可变的强类型接口
struct Temperature {
    double kelvin;
};

Temperature boil(const Temperature& water);

错误示例 (DON'T)

// 弱接口：所有权不明确，单位不明确
double boil(double* temp);

// 非 const 全局变量
int g_counter = 0;  // 违反 I.2

函数 (F.*)

核心规则

| 规则 | 摘要 | |------|---------| | **F.1** | 将有意义的操作打包成命名谨慎的函数 | | **F.2** | 函数应执行单一逻辑操作 | | **F.3** | 保持函数简短且简单 | | **F.4** | 如果函数可能在编译时求值，请将其声明为 `constexpr` | | **F.6** | 如果函数绝不抛出异常，请将其声明为 `noexcept` | | **F.8** | 优先选择纯函数 (Pure functions) | | **F.16** | 对于“输入”参数，低开销拷贝类型按值传递，其他类型按 `const&` 传递 | | **F.20** | 对于“输出”值，优先选择返回值而非输出参数 | | **F.21** | 若要返回多个“输出”值，优先返回结构体 | | **F.43** | 绝不返回指向局部对象的指针或引用 |

参数传递

// F.16: 低开销类型按值传递，其他按 const& 传递
void print(int x);                           // 低开销：按值
void analyze(const std::string& data);       // 高开销：按 const&
void transform(std::string s);               // 接收端：按值（将触发 move）

// F.20 + F.21: 使用返回值，而非输出参数
struct ParseResult {
    std::string token;
    int position;
};

ParseResult parse(std::string_view input);   // 推荐：返回结构体

// 不良实践：使用输出参数
void parse(std::string_view input,
           std::string& token, int& pos);    // 避免这样做

纯函数与 constexpr

// F.4 + F.8: 尽可能使用纯函数和 constexpr
constexpr int factorial(int n) noexcept {
    return (n <= 1) ? 1 : n * factorial(n - 1);
}

static_assert(factorial(5) == 120);

反模式 (Anti-Patterns)

• 从函数返回 `T&&` (F.45)
• 使用 `va_arg` / C 风格变长参数 (F.55)
• 在传递给其他线程的 lambda 中按引用捕获 (F.53)
• 返回 `const T`，这会抑制移动语义 (F.49)

类与类层次结构 (C.*)

核心规则

| 规则 | 摘要 | |------|---------| | **C.2** | 如果存在不变式 (Invariant)，使用 `class`；如果成员数据独立变化，使用 `struct` | | **C.9** | 最小化成员的公开暴露 | | **C.20** | 如果可以避免定义默认操作，则不要定义（零法则 Rule of Zero） | | **C.21** | 如果定义或 `=delete` 了任何拷贝/移动/析构函数，请处理所有五个（五法则 Rule of Five） | | **C.35** | 基类析构函数：要么是 public virtual，要么是 protected non-virtual | | **C.41** | 构造函数应创建一个完全初始化的对象 | | **C.46** | 将单参数构造函数声明为 `explicit` | | **C.67** | 多态类 (Polymorphic class) 应抑制公开的拷贝/移动 | | **C.128** | 虚函数：必须精确指定 `virtual`、`override` 或 `final` 中的一个 |

零法则 (Rule of Zero)

// C.20: 让编译器生成特殊成员
struct Employee {
    std::string name;
    std::string department;
    int id;
    // 无需析构函数、拷贝/移动构造函数或赋值运算符
};

五法则 (Rule of Five)

// C.21: 如果必须管理资源，请定义所有五个
class Buffer {
public:
    explicit Buffer(std::size_t size)
        : data_(std::make_unique<char[]>(size)), size_(size) {}

    ~Buffer() = default;

    Buffer(const Buffer& other)
        : data_(std::make_unique<char[]>(other.size_)), size_(other.size_) {
        std::copy_n(other.data_.get(), size_, data_.get());
    }

    Buffer& operator=(const Buffer& other) {
        if (this != &other) {
            auto new_data = std::make_unique<char[]>(other.size_);
            std::copy_n(other.data_.get(), other.size_, new_data.get());
            data_ = std::move(new_data);
            size_ = other.size_;
        }
        return *this;
    }

    Buffer(Buffer&&) noexcept = default;
    Buffer& operator=(Buffer&&) noexcept = default;

private:
    std::unique_ptr<char[]> data_;
    std::size_t size_;
};

类层次结构

// C.35 + C.128: 虚析构函数，使用 override
class Shape {
public:
    virtual ~Shape() = default;
    virtual double area() const = 0;  // C.121: 纯接口
};

class Circle : public Shape {
public:
    explicit Circle(double r) : radius_(r) {}
    double area() const override { return 3.14159 * radius_ * radius_; }

private:
    double radius_;
};

反模式 (Anti-Patterns)

• 在构造函数/析构函数中调用虚函数 (C.82)
• 对非平凡 (Non-trivial) 类型使用 `memset`/`memcpy` (C.90)
• 为虚函数及其覆盖者提供不同的默认参数 (C.140)
• 使数据成员成为 `const` 或引用，这会抑制移动/拷贝 (C.12)

资源管理 (R.*)

核心规则

| 规则 | 摘要 | |------|---------| | **R.1** | 使用 RAII 自动管理资源 | | **R.3** | 原始指针 (`T*`) 是非所有权的 | | **R.5** | 优先选择作用域对象；不要不必要地在堆上分配 | | **R.10** | 避免使用 `malloc()`/`free()` | | **R.11** | 避免显式调用 `new` 和 `delete` | | **R.20** | 使用 `unique_ptr` 或 `shared_ptr` 表示所有权 | | **R.21** | 除非共享所有权，否则优先选择 `unique_ptr` 而非 `shared_ptr` | | **R.22** | 使用 `make_shared()` 创建 `shared_ptr` |

智能指针用法

// R.11 + R.20 + R.21: 使用智能指针进行 RAII
auto widget = std::make_unique<Widget>("config");  // 独占所有权
auto cache  = std::make_shared<Cache>(1024);        // 共享所有权

// R.3: 原始指针 = 非所有权的观察者
void render(const Widget* w) {  // 不拥有 w
    if (w) w->draw();
}

render(widget.get());

RAII 模式

// R.1: 资源获取即初始化 (Resource acquisition is initialization)
class FileHandle {
public:
    explicit FileHandle(const std::string& path)
        : handle_(std::fopen(path.c_str(), "r")) {
        if (!handl