| name | cpp-coding-standards |
| description | 基于 C++ 核心指南 (isocpp.github.io) 的 C++ 编码规范。在编写、评审或重构 C++ 代码时使用，以强制执行现代、安全且地道的实践。 |
| origin | ECC |
C++ 编码规范 (C++ Core Guidelines)
源自 C++ 核心指南 (C++ Core Guidelines) 的现代 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)
以下主题贯穿整个指南并构成基础：
- 处处 RAII (P.8, R.1, E.6, CP.20)：将资源生命周期与对象生命周期绑定。资源获取即初始化 (RAII)
- 默认不变性 (P.10, Con.1-5, ES.25)：优先使用
const/constexpr；可变性应当是例外。不变性 (Immutability)
- 类型安全 (P.4, I.4, ES.46-49, Enum.3)：利用类型系统在编译时防止错误。类型安全 (Type safety)
- 表达意图 (P.3, F.1, NL.1-2, T.10)：名称、类型和概念应能传达目的。表达意图 (Express intent)
- 最小化复杂性 (F.2-3, ES.5, Per.4-5)：简单的代码才是正确的代码
- 值语义优于指针语义 (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)
struct Temperature {
double kelvin;
};
Temperature boil(const Temperature& water);
错误示例 (DON'T)
double boil(double* temp);
int g_counter = 0;
函数 (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 | 绝不返回指向局部对象的指针或引用 |
参数传递
void print(int x);
void analyze(const std::string& data);
void transform(std::string s);
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
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)
struct Employee {
std::string name;
std::string department;
int id;
};
五法则 (Rule of Five)
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_;
};
类层次结构
class Shape {
public:
virtual ~Shape() = default;
virtual double area() const = 0;
};
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 |
智能指针用法
auto widget = std::make_unique<Widget>("config");
auto cache = std::make_shared<Cache>(1024);
void render(const Widget* w) {
if (w) w->draw();
}
render(widget.get());
RAII 模式
class FileHandle {
public:
explicit FileHandle(const std::string& path)
: handle_(std::fopen(path.c_str(), "r")) {
if (!handle_) throw std::runtime_error("Failed to open: " + 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_;
};
反模式 (Anti-Patterns)
- 裸
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 | 对 const 变量的复杂初始化使用 lambda |
| ES.45 | 避免幻数 (Magic constants)；使用符号常量 |
| ES.46 | 避免收窄/有损的算术转换 |
| ES.47 | 使用 nullptr 而非 0 或 NULL |
| ES.48 | 避免强制类型转换 (Casts) |
| ES.50 | 不要转换掉 const 属性 |
初始化
const int max_retries{3};
const std::string name{"widget"};
const std::vector<int> primes{2, 3, 5, 7, 11};
const auto config = [&] {
Config c;
c.timeout = std::chrono::seconds{30};
c.retries = max_retries;
c.verbose = debug_mode;
return c;
}();
反模式 (Anti-Patterns)
- 未初始化的变量 (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 | 析构函数、释放操作和 swap 绝不能失败 |
| E.17 | 不要试图在每个函数中捕获每个异常 |
异常层次结构
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) {
throw NetworkError("connection refused", 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());
}
}
反模式 (Anti-Patterns)
- 抛出内置类型如
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 |
class Sensor {
public:
explicit Sensor(std::string id) : id_(std::move(id)) {}
const std::string& id() const { return id_; }
double last_reading() const { return reading_; }
void record(double value) { reading_ = value; }
private:
const std::string id_;
double reading_{0.0};
};
void display(const Sensor& s) {
std::cout << s.id() << ": " << s.last_reading() << '\n';
}
constexpr double PI = 3.14159265358979;
constexpr int MAX_SENSORS = 256;
并发与并行 (CP.*)
核心规则
| 规则 | 摘要 |
|---|
| CP.2 | 避免数据竞态 (Data races) |
| CP.3 | 最小化显式共享可写数据 |
| CP.4 | 以任务 (Tasks) 而非线程 (Threads) 的方式思考 |
| 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 | 除非绝对必要，否则不要使用无锁编程 (Lock-free programming) |
安全加锁
class ThreadSafeQueue {
public:
void push(int value) {
std::lock_guard<std::mutex> lock(mutex_);
queue_.push(value);
cv_.notify_one();
}
int pop() {
std::unique_lock<std::mutex> lock(mutex_);
cv_.wait(lock, [this] { return !queue_.empty(); });
const int value = queue_.front();
queue_.pop();
return value;
}
private:
std::mutex mutex_;
std::condition_variable cv_;
std::queue<int> queue_;
};
多个互斥锁
void transfer(Account& from, Account& to, double amount) {
std::scoped_lock lock(from.mutex_, to.mutex_);
from.balance_ -= amount;
to.balance_ += amount;
}
反模式 (Anti-Patterns)
- 使用
volatile 进行同步 (CP.8 —— 它仅用于硬件 I/O)
- 分离线程 (Detaching threads) (CP.26 —— 生命周期管理将变得几乎不可能)
- 未命名的锁保护：
std::lock_guard<std::mutex>(m); 会立即销毁 (CP.44)
- 调用回调时持有锁 (CP.22 —— 死锁风险)
- 缺乏深厚专业知识却进行无锁编程 (CP.100)
模板与泛型编程 (T.*)
核心规则
| 规则 | 摘要 |
|---|
| T.1 | 使用模板提升抽象层级 |
| T.2 | 使用模板为多种参数类型表达算法 |
| T.10 | 为所有模板参数指定概念 (Concepts) |
| T.11 | 尽可能使用标准概念 |
| T.13 | 简单概念优先使用简写表示法 |
| T.43 | 优先选择 using 而非 typedef |
| T.120 | 仅在确实需要时使用模板元编程 (Template metaprogramming) |
| T.144 | 不要特化函数模板（应使用重载） |
概念 Concepts (C++20)
#include <concepts>
template<std::integral T>
T gcd(T a, T b) {
while (b != 0) {
a = std::exchange(b, a % b);
}
return a;
}
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);
反模式 (Anti-Patterns)
- 可见命名空间中使用无约束模板 (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 会强制刷新缓冲区） |
const std::array<int, 4> fixed_data{1, 2, 3, 4};
std::vector<std::string> dynamic_data;
std::string build_greeting(std::string_view name) {
return "Hello, " + std::string(name) + "!";
}
std::cout << "result: " << value << '\n';
枚举 (Enum.*)
核心规则
| 规则 | 摘要 |
|---|
| Enum.1 | 优先选择枚举而非宏 |
| Enum.3 | 优先选择 enum class 而非普通 enum |
| Enum.5 | 不要对枚举成员使用 全大写 (ALL_CAPS) 命名 |
| Enum.6 | 避免使用匿名枚举 |
enum class Color { red, green, blue };
enum class LogLevel { debug, info, warning, error };
enum { RED, GREEN, BLUE };
#define MAX_SIZE 100
源文件与命名 (SF., NL.)
核心规则
| 规则 | 摘要 |
|---|
| SF.1 | 代码文件使用 .cpp，接口文件使用 .h |
| SF.7 | 不要在头文件的全局作用域编写 using namespace |
| SF.8 | 为所有 .h 文件使用 #include 保护 |
| SF.11 | 头文件应当是自包含的 (Self-contained) |
| NL.5 | 避免在名称中编码类型信息（不使用匈牙利命名法） |
| NL.8 | 使用一致的命名风格 |
| NL.9 | 仅对宏名称使用 全大写 (ALL_CAPS) |
| NL.10 | 优先选择 下划线风格 (underscore_style) 命名 |
头文件保护 (Header Guard)
#ifndef PROJECT_MODULE_WIDGET_H
#define PROJECT_MODULE_WIDGET_H
#include <string>
#include <vector>
namespace project::module {
class Widget {
public:
explicit Widget(std::string name);
const std::string& name() const;
private:
std::string name_;
};
}
#endif
命名规范
namespace my_project {
constexpr int max_buffer_size = 4096;
class tcp_connection {
public:
void send_message(std::string_view msg);
bool is_connected() const;
private:
std::string host_;
int port_;
};
}
反模式 (Anti-Patterns)
- 头文件全局作用域中使用
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 | 以可预测的方式访问内存 |
指南
constexpr auto lookup_table = [] {
std::array<int, 256> table{};
for (int i = 0; i < 256; ++i) {
table[i] = i * i;
}
return table;
}();
std::vector<Point> points;
std::vector<std::unique_ptr<Point>> indirect_points;
反模式 (Anti-Patterns)
- 在没有性能分析数据的情况下进行优化 (Per.1, Per.6)
- 选择“聪明”的低级代码而非清晰的抽象 (Per.4, Per.5)
- 忽视数据布局和缓存行为 (Per.19)
快速参考自检清单
在标记 C++ 工作完成之前：
