C++ 代码规范与格式化指南

1. C++ 代码规范与格式化指南

代码规范（Code Style）和格式化（Formatting）是团队协作中不可或缺的一环。统一的代码风格不仅能提升代码可读性、降低维护成本，还能有效减少 Code Review 中的风格争议。本文将从命名规范、缩进排版、注释写法和自动化工具几个维度，系统梳理 C++ 项目中的常见规范实践。

2. 命名规范

良好的命名是自注释代码的第一步。下面按 C++ 中常见的命名对象分类说明：

2.1 类与结构体

类名和结构体名推荐使用大驼峰命名法（PascalCase），每个单词首字母大写：

cpp 复制代码

class HttpRequestHandler { };
class ThreadPoolManager { };
struct Point3D { };

2.2 函数与方法

函数名通常也采用大驼峰或小驼峰，取决于项目惯例。Google C++ Style Guide 推荐大驼峰：

cpp 复制代码

void StartListening();
int GetMaxConnections();
double CalculateDistance(const Point3D& a, const Point3D& b);

2.3 变量与成员变量

局部变量和形参使用小写加下划线（snake_case），成员变量在末尾加下划线以区分：

cpp 复制代码

int total_count = 0;
std::string user_name;
class Server {
private:
    int max_connections_;
    std::string host_name_;
};

2.4 常量与枚举

常量通常以 k 开头后跟大驼峰，或全大写加下划线：

cpp 复制代码

const int kDefaultPort = 8080;
const double PI = 3.1415926535;
enum class Color { Red, Green, Blue };

2.5 宏

宏名全部大写，单词间用下划线分隔：

cpp 复制代码

#define MAX_BUFFER_SIZE 4096
#define LOG_ERROR(msg) std::cerr << msg << std::endl

注意：现代 C++ 应尽量用 constexpr 或 inline 函数替代宏。

3. 缩进与排版

3.1 缩进宽度

主流风格为 2 空格或 4 空格。Google 风格使用 2 空格，LLVM 风格使用 2 空格，GNU 风格使用 2 空格但在某些场景有不同对齐规则。标签与空格混用是绝对禁止的。

3.2 大括号换行

常见的两种风格：

K&R 风格（Google / LLVM 采用）：左大括号不换行。
Allman 风格：左大括号独占一行，视觉对称性更强。

cpp 复制代码

// K&R 风格
if (condition) {
    DoWork();
}
// Allman 风格
if (condition)
{
DoWork();
}

团队应统一选择其中一种，避免混用。

3.3 行宽限制

推荐单行不超过 80 或 120 个字符。长函数声明可采用参数换行对齐：

cpp 复制代码

void VeryLongFunctionName(
    const std::string& param1,
    const std::vector<int>& param2,
    int param3);

3.4 空行与空格

函数之间保留一个空行。
逻辑段落之间用空行分隔。
二元运算符两侧留空格（a + b），一元运算符不留（!flag）。
关键字后留空格：if (、for (、while (。
函数名与左括号之间不留空格：func()。

4. 注释规范

4.1 文件头注释

cpp 复制代码

// Copyright 2026 MyCompany. All rights reserved.
// @file: http_handler.cpp
// @brief: HTTP 请求处理模块实现。

4.2 函数与类注释

公共接口推荐使用 Doxygen 风格注释，便于自动生成文档：

cpp 复制代码

/**
 * @brief 计算两点间欧氏距离。
 * @param a 第一个点。
 * @param b 第二个点。
 * @return 两点之间的直线距离。
 */
double EuclideanDistance(const Point3D& a, const Point3D& b);

4.3 内联注释

解释为什么这样做而非做了什么，复杂算法段落补充必要的行内注释，避免无意义注释：

cpp 复制代码

// 使用二分查找而非线性扫描，数据量超过 10 万时性能差距显著。
auto it = std::lower_bound(data.begin(), data.end(), target);
// 坏示例：多余的废话
// count 自增 1
++count;

4.4 TODO 标记

统一使用 TODO(username) 格式，方便检索和跟进：

cpp 复制代码

// TODO(zhangsan): 后续需支持 IPv6 地址解析。

5. 现代 C++ 特性使用建议

优先使用智能指针： 用 std::unique_ptr 和 std::shared_ptr 替代裸指针，避免内存泄漏。
善用 auto： 在类型明显或模板场景使用 auto 减少冗余。
范围 for 循环： 遍历容器时优先使用 for (const auto& item : container)。
nullptr 代替 NULL： C++11 起统一使用 nullptr。
**override 关键字：**重写虚函数时显式标注，降低错误风险。
强类型枚举： 优先使用 enum class 而非传统 enum。

6. 自动化格式化工具

手工维护代码风格费时且容易遗漏，推荐在项目中集成自动化格式化工具：

6.1 clang-format

Clang 官方提供的格式化工具，支持 LLVM / Google / Chromium / Mozilla / WebKit 等预设风格，也可通过 .clang-format 文件自定义规则。常用配置项：

yaml 复制代码

BasedOnStyle: Google
IndentWidth: 2
ColumnLimit: 120
BreakBeforeBraces: Attach
AllowShortFunctionsOnASingleLine: Empty

在 VS Code、CLion 等 IDE 中可配置保存时自动格式化。

6.2 集成到 CI/CD

将格式化检查加入持续集成流水线，确保提交的代码风格统一：

bash 复制代码

# 检查模式，CI 中通常用 --dry-run
clang-format --dry-run --Werror src/*.cpp
批量格式化
clang-format -i src/.cpp src/.h

配合 pre-commit hook 或 Git 钩子，可在本地提交阶段拦截风格不规范的代码。

C++ 代码规范涵盖命名、排版、注释和工具链四个层面。核心原则是：

**团队一致：**选一套风格并坚持到底，风格本身没有绝对优劣。
**工具赋能：**clang-format 等工具能自动消除大部分风格差异。
**持续迭代：**随着 C++ 标准演进，规范也应及时更新。

规范的最终目标是让代码成为团队的共同语言，而不是某个人的私人笔记。希望本文能为你的 C++ 项目规范化提供一份实用参考。