cpp-coding-standards

name	cpp-coding-standards
description	基于 C++ Core Guidelines (isocpp.github.io) 的 C++ 编码标准。在编写、审查或重构 C++ 代码时使用，以强制执行现代、安全和地道的实践。
origin	ECC

C++ 编码标准（C++ Core Guidelines）

源自 C++ Core Guidelines 的现代 C++（C++17/20/23）综合编码标准。强制类型安全、资源安全、不可变性和清晰性。

何时使用

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

何时不使用

• 非 C++ 项目
• 无法采用现代 C++ 特性的遗留 C 代码库
• 特定指南与硬件约束冲突的嵌入式/裸机环境（选择性适配）

跨领域原则

这些主题贯穿整个指南并构成基础：

1. 无处不在的 RAII（P.8, R.1, E.6, CP.20）：将资源生命周期绑定到对象生命周期
2. 默认不可变（P.10, Con.1-5, ES.25）：从 const/constexpr 开始；可变性是例外
3. 类型安全（P.4, I.4, ES.46-49, Enum.3）：使用类型系统在编译时防止错误
4. 表达意图（P.3, F.1, NL.1-2, T.10）：名称、类型和概念应该传达目的
5. 最小化复杂度（F.2-3, ES.5, Per.4-5）：简单的代码就是正确的代码
6. 值语义优于指针语义（C.10, R.3-5, F.20, CP.31）：优先按值返回和使用作用域对象

哲学与接口（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	保持函数参数数量少

应该

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

Temperature boil(const Temperature& water);

不应该

// 弱接口：不清楚的所有权，不清楚的单位
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	优先纯函数
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);               // 接收端：按值（将移动）

// 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);

反模式

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

类与类层次结构（C.*）

关键规则

规则	摘要
C.2	如果存在不变量则使用 class；如果数据成员独立变化则使用 struct
C.9	最小化成员暴露
C.20	如果能避免定义默认操作，就避免（零规则）
C.21	如果定义或 =delete 任何复制/移动/析构，就处理它们全部（五规则）
C.35	基类析构函数：public virtual 或 protected non-virtual
C.41	构造函数应该创建完全初始化的对象
C.46	将单参数构造函数声明为 explicit
C.67	多态类应抑制 public 复制/移动
C.128	虚函数：精确指定 virtual、override 或 final 中的一个

零规则

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

五规则

// 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_;
};

反模式

• 在构造函数/析构函数中调用虚函数（C.82）
• 对非平凡类型使用 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: 资源获取即初始化
class FileHandle {
public:
    explicit FileHandle(const std::string& path)
        : handle_(std::fopen(path.c_str(), "r")) {
        if (!handle_) throw std::runtime_error("打开失败: " + path);
    }

    ~FileHandle() {
        if (handle_) std::fclose(handle_);
    }

    FileHandle(const FileHandle&) = delete;
    FileHandle& operator=(const FileHandle&) = delete;
    FileHandle(FileHandle&& other) noexcept
        : handle_(std::exchange(other.handle_, nullptr)) {}
    FileHandle& operator=(FileHandle&& other) noexcept {
        if (this != &other) {
            if (handle_) std::fclose(handle_);
            handle_ = std::exchange(other.handle_, nullptr);
        }
        return *this;
    }

private:
    std::FILE* handle_;
};

反模式

• 裸 new/delete（R.11）
• C++ 代码中的 malloc()/free()（R.10）
• 单个表达式中的多重资源分配（R.13 — 异常安全风险）
• 在 unique_ptr 就够用时使用 shared_ptr（R.21）

表达式与语句（ES.*）

关键规则

规则	摘要
ES.5	保持作用域小
ES.20	始终初始化对象
ES.23	优先 {} 初始化语法
ES.25	除非有意修改，否则将对象声明为 const 或 constexpr
ES.28	使用 lambda 对 const 变量进行复杂初始化
ES.45	避免魔法常量；使用符号常量
ES.46	避免窄化/有损算术转换
ES.47	使用 nullptr 而非 0 或 NULL
ES.48	避免类型转换
ES.50	不要去除 const

初始化

// ES.20 + ES.23 + ES.25: 始终初始化，优先 {}，默认 const
const int max_retries{3};
const std::string name{"widget"};
const std::vector<int> primes{2, 3, 5, 7, 11};

// ES.28: Lambda 用于复杂的 const 初始化
const auto config = [&] {
    Config c;
    c.timeout = std::chrono::seconds{30};
    c.retries = max_retries;
    c.verbose = debug_mode;
    return c;
}();

反模式

• 未初始化变量（ES.20）
• 使用 0 或 NULL 作为指针（ES.47 — 使用 nullptr）
• C 风格类型转换（ES.48 — 使用 static_cast、const_cast 等）
• 去除 const（ES.50）
• 没有命名常量的魔法数字（ES.45）
• 混合有符号和无符号算术（ES.100）
• 在嵌套作用域中重用名称（ES.12）

错误处理（E.*）

关键规则

规则	摘要
E.1	在设计早期制定错误处理策略
E.2	抛出异常以表示函数无法完成其分配的任务
E.6	使用 RAII 防止泄漏
E.12	当抛出不可能或不可接受时使用 noexcept
E.14	使用专门设计的用户自定义类型作为异常
E.15	按值抛出，按引用捕获
E.16	析构函数、释放和交换必须绝不失败
E.17	不要试图在每个函数中捕获每个异常

异常层次结构

// E.14 + E.15: 自定义异常类型，按值抛出，按引用捕获
class AppError : public std::runtime_error {
public:
    using std::runtime_error::runtime_error;
};

class NetworkError : public AppError {
public:
    NetworkError(const std::string& msg, int code)
        : AppError(msg), status_code(code) {}
    int status_code;
};

void fetch_data(const std::string& url) {
    // E.2: 抛出以表示失败
    throw NetworkError("连接被拒绝", 503);
}

void run() {
    try {
        fetch_data("https://api.example.com");
    } catch (const NetworkError& e) {
        log_error(e.what(), e.status_code);
    } catch (const AppError& e) {
        log_error(e.what());
    }
    // E.17: 不要在这里捕获所有内容 — 让意外错误传播
}

反模式

• 抛出内置类型如 int 或字符串字面量（E.14）
• 按值捕获（切片风险）（E.15）
• 静默吞没错误的空 catch 块
• 使用异常进行流程控制（E.3）
• 基于全局状态如 errno 的错误处理（E.28）

常量与不可变性（Con.*）

所有规则

规则	摘要
Con.1	默认情况下，使对象不可变
Con.2	默认情况下，使成员函数为 const
Con.3	默认情况下，传递指向 const 的指针和引用
Con.4	对构造后不变的值使用 const
Con.5	对可在编译时计算的值使用 constexpr

// Con.1 到 Con.5: 默认不可变
class Sensor {
public:
    explicit Sensor(std::string id) : id_(std::move(id)) {}

    // Con.2: 默认 const 成员函数
    const std::string& id() const { return id_; }
    double last_reading() const { return reading_; }

    // 仅当需要修改时为非 const
    void record(double value) { reading_ = value; }

private:
    const std::string id_;  // Con.4: 构造后永不改变
    double reading_{0.0};
};

// Con.3: 按 const 引用传递
void display(const Sensor& s) {
    std::cout << s.id() << ": " << s.last_reading() << '\n';
}

// Con.5: 编译时常量
constexpr double PI = 3.14159265358979;
constexpr int MAX_SENSORS = 256;

并发与并行（CP.*）

关键规则

规则	摘要
CP.2	避免数据竞争
CP.3	最小化可写数据的显式共享
CP.4	以任务而非线程的方式思考
CP.8	不要使用 volatile 进行同步
CP.20	使用 RAII，绝不使用裸 lock()/unlock()
CP.21	使用 std::scoped_lock 获取多个互斥锁
CP.22	持有锁时绝不调用未知代码
CP.42	不要无条件等待（始终配合条件）
CP.44	记住给你的 lock_guard 和 unique_lock 命名
CP.100	除非绝对必要，不要使用无锁编程

安全锁定

// CP.20 + CP.44: RAII 锁，始终命名
class ThreadSafeQueue {
public:
    void push(int value) {
        std::lock_guard<std::mutex> lock(mutex_);  // CP.44: 命名了！
        queue_.push(value);
        cv_.notify_one();
    }

    int pop() {
        std::unique_lock<std::mutex> lock(mutex_);
        // CP.42: 始终带条件等待
        cv_.wait(lock, [this] { return !queue_.empty(); });
        const int value = queue_.front();
        queue_.pop();
        return value;
    }

private:
    std::mutex mutex_;             // CP.50: 互斥锁与其数据放在一起
    std::condition_variable cv_;
    std::queue<int> queue_;
};

多个互斥锁

// CP.21: std::scoped_lock 用于多个互斥锁（无死锁）
void transfer(Account& from, Account& to, double amount) {
    std::scoped_lock lock(from.mutex_, to.mutex_);
    from.balance_ -= amount;
    to.balance_ += amount;
}

反模式

• volatile 用于同步（CP.8 — 它仅用于硬件 I/O）
• 分离线程（CP.26 — 生命周期管理变得几乎不可能）
• 未命名的锁保护：std::lock_guard<std::mutex>(m); 立即销毁（CP.44）
• 持有锁时调用回调（CP.22 — 死锁风险）
• 没有深厚专业知识就使用无锁编程（CP.100）

模板与泛型编程（T.*）

关键规则

规则	摘要
T.1	使用模板提高抽象层次
T.2	使用模板表达适用于多种参数类型的算法
T.10	为所有模板参数指定概念
T.11	尽可能使用标准概念
T.13	对简单概念优先使用简写表示法
T.43	优先 using 而非 typedef
T.120	仅在真正需要时使用模板元编程
T.144	不要特化函数模板（改用重载）

概念（C++20）

#include <concepts>

// T.10 + T.11: 用标准概念约束模板
template<std::integral T>
T gcd(T a, T b) {
    while (b != 0) {
        a = std::exchange(b, a % b);
    }
    return a;
}

// T.13: 简写概念语法
void sort(std::ranges::random_access_range auto& range) {
    std::ranges::sort(range);
}

// 领域特定约束的自定义概念
template<typename T>
concept Serializable = requires(const T& t) {
    { t.serialize() } -> std::convertible_to<std::string>;
};

template<Serializable T>
void save(const T& obj, const std::string& path);

反模式

• 可见命名空间中无约束的模板（T.47）
• 特化函数模板而非重载（T.144）
• 在 constexpr 就够用时使用模板元编程（T.120）
• 使用 typedef 而非 using（T.43）

标准库（SL.*）

关键规则

规则	摘要
SL.1	尽可能使用库
SL.2	优先标准库而非其他库
SL.con.1	优先 std::array 或 std::vector 而非 C 数组
SL.con.2	默认优先 std::vector
SL.str.1	使用 std::string 拥有字符序列
SL.str.2	使用 std::string_view 引用字符序列
SL.io.50	避免 endl（使用 '\n' — endl 强制刷新）

// SL.con.1 + SL.con.2: 优先 vector/array 而非 C 数组
const std::array<int, 4> fixed_data{1, 2, 3, 4};
std::vector<std::string> dynamic_data;

// SL.str.1 + SL.str.2: string 拥有，string_view 观察
std::string build_greeting(std::string_view name) {
    return "Hello, " + std::string(name) + "!";
}

// SL.io.50: 使用 '\n' 而非 endl
std::cout << "result: " << value << '\n';

枚举（Enum.*）

关键规则

规则	摘要
Enum.1	优先枚举而非宏
Enum.3	优先 enum class 而非普通 enum
Enum.5	不要对枚举器使用全大写
Enum.6	避免未命名的枚举

// Enum.3 + Enum.5: 作用域枚举，无全大写
enum class Color { red, green, blue };
enum class LogLevel { debug, info, warning, error };

// 差：普通枚举泄漏名称，全大写与宏冲突
enum { RED, GREEN, BLUE };           // Enum.3 + Enum.5 + Enum.6 违规
#define MAX_SIZE 100                  // Enum.1 违规 — 使用 constexpr

源文件与命名（SF., NL.）

关键规则

规则	摘要
SF.1	代码文件使用 .cpp，接口文件使用 .h
SF.7	不要在头文件的全局作用域写 using namespace
SF.8	所有 .h 文件使用 #include 保护
SF.11	头文件应该自包含
NL.5	避免在名称中编码类型信息（不要匈牙利命名法）
NL.8	使用一致的命名风格
NL.9	仅对宏名称使用全大写
NL.10	优先 下划线风格 命名

头文件保护

// SF.8: 包含保护（或 #pragma once）
#ifndef PROJECT_MODULE_WIDGET_H
#define PROJECT_MODULE_WIDGET_H

// SF.11: 自包含 — 包含此头文件需要的一切
#include <string>
#include <vector>

namespace project::module {

class Widget {
public:
    explicit Widget(std::string name);
    const std::string& name() const;

private:
    std::string name_;
};

}  // namespace project::module

#endif  // PROJECT_MODULE_WIDGET_H

命名约定

// NL.8 + NL.10: 一致的下划线风格
namespace my_project {

constexpr int max_buffer_size = 4096;  // NL.9: 不全大写（不是宏）

class tcp_connection {                 // 下划线风格类名
public:
    void send_message(std::string_view msg);
    bool is_connected() const;

private:
    std::string host_;                 // 尾下划线表示成员
    int port_;
};

}  // namespace my_project

反模式

• 在头文件全局作用域中使用 using namespace std;（SF.7）
• 依赖包含顺序的头文件（SF.10, SF.11）
• 匈牙利命名法如 strName、iCount（NL.5）
• 除宏外任何东西使用全大写（NL.9）

性能（Per.*）

关键规则

规则	摘要
Per.1	不要无理由地优化
Per.2	不要过早优化
Per.6	不要在没有测量数据的情况下做性能声明
Per.7	设计以支持优化
Per.10	依赖静态类型系统
Per.11	将计算从运行时移到编译时
Per.19	以可预测的方式访问内存

指南

// Per.11: 尽可能编译时计算
constexpr auto lookup_table = [] {
    std::array<int, 256> table{};
    for (int i = 0; i < 256; ++i) {
        table[i] = i * i;
    }
    return table;
}();

// Per.19: 优先连续数据以利于缓存
std::vector<Point> points;           // 好：连续
std::vector<std::unique_ptr<Point>> indirect_points; // 差：指针追踪

反模式

• 没有性能分析数据就优化（Per.1, Per.6）
• 选择"聪明的"底层代码而非清晰的抽象（Per.4, Per.5）
• 忽略数据布局和缓存行为（Per.19）

快速参考检查清单

在标记 C++ 工作完成之前：

• 无裸 new/delete — 使用智能指针或 RAII（R.11）
• 对象在声明时初始化（ES.20）
• 变量默认为 const/constexpr（Con.1, ES.25）
• 成员函数尽可能为 const（Con.2）
• 使用 enum class 而非普通 enum（Enum.3）
• 使用 nullptr 而非 0/NULL（ES.47）
• 无窄化转换（ES.46）
• 无 C 风格类型转换（ES.48）
• 单参数构造函数为 explicit（C.46）
• 应用零规则或五规则（C.20, C.21）
• 基类析构函数为 public virtual 或 protected non-virtual（C.35）
• 模板使用概念约束（T.10）
• 头文件全局作用域中无 using namespace（SF.7）
• 头文件有包含保护且自包含（SF.8, SF.11）
• 锁使用 RAII（scoped_lock/lock_guard）（CP.20）
• 异常为自定义类型，按值抛出，按引用捕获（E.14, E.15）
• 使用 '\n' 而非 std::endl（SL.io.50）
• 无魔法数字（ES.45）