C++ 代码规范文章

棱光智构-lightning visio 2026-01-02 16:10:22

一、通用核心原则

可读性优先：代码需清晰表达意图，命名、注释直观易懂。
风格统一：团队内命名、格式、注释保持一致，借助工具强制规范。
单一职责：函数 / 类 / 模块专注单一功能，避免功能耦合。
可测试性：设计支持单元测试，便于自动化验证与缺陷定位。
安全优先：编码阶段规避空指针、越界等风险，优先使用安全特性。
性能与可维护性平衡：关键路径优化性能，非敏感场景优先保证可维护性。

二、命名规范

元素类型	命名规则	示例
变量 / 常量	局部变量：小驼峰（camelCase）；常量：全大写 + 下划线（UPPER_SNAKE_CASE），优先用 `constexpr` / `const`	局部变量：`imagePath`；常量：`MAX_FILTER_SIZE = 3`
函数 / 方法	小驼峰 + 动词开头，避免单字母命名	`loadImage()`、`applyGaussianBlur()`
类 / 结构体	PascalCase，体现对象本质	`ImageProcessor`、`EdgeDetector`
命名空间	全小写，可按模块 / 项目名划分	`namespace image_processing`
宏定义	全大写 + 下划线，仅用于必要的编译期常量	`#define IMAGE_WIDTH 640`
枚举类型	枚举名用帕斯卡，枚举值全大写 + 下划线	`enum ImageType { IMAGE_GRAYSCALE, IMAGE_COLOR };`
模板参数	单个大写字母或有意义的单词	`template <typename T>`、`template <typename PixelType>`

三、代码格式规范

缩进与换行

统一用 4 个空格（禁止 Tab），避免混合缩进。
大括号 { 与声明同行（如 if (cond) {），} 单独占行并与声明对齐。
长表达式换行：在低优先级运算符（如 +、&&）后换行，缩进 2 级（8 个空格），例如：
```
result = cv::addWeighted(originalImage, alpha, 
                        overlayImage, beta, gamma);
```

行宽与空格

单行代码不超过 120 字符，超长字符串用 R"()" 原始字符串或拼接。
操作符（+、=、==）前后、逗号后必须加空格（如 a = b + c，非 a=b+c）。
逻辑块（函数、循环、条件）之间用 1 行空行分隔，变量定义与主逻辑间加空行。

语句规范

一行仅写一条语句，禁止 if (cond) doA(); else doB();（需分行）。
变量声明优先初始化（如 int sum = 0;，非 int sum;），局部变量尽量靠近使用位置。

四、注释规范

注释类型与要求

文件头部注释：包含文件名、作者、功能、创建时间、修改记录，例如：

/*
 * File: edge_detection.cpp
 * Author: XXX
 * Function: Perform edge detection on images using OpenCV
 * Create Time: 2025-09-10
 * Modify Record: None
 */

函数 / 类注释：描述功能、参数（含义 / 取值范围）、返回值、异常，优先用 Doxygen 格式，例如：

/**
 * @brief Apply Gaussian blur to an image
 * @param inputImage Input image (must not be empty)
 * @param kernelSize Size of the Gaussian kernel (must be odd)
 * @return Blurred image (cv::Mat)
 * @throw std::invalid_argument If input image is empty or kernel size is even
 */
cv::Mat applyGaussianBlur(const cv::Mat& inputImage, int kernelSize);

行内注释：仅解释复杂逻辑（如 // Skip pixels with intensity below threshold），禁止冗余注释（如 i++;// Increment i）。
TODO 注释：标记待完善内容（如 // TODO: Optimize image resizing algorithm），删除无用代码（禁止注释掉旧代码）。

同步更新

代码修改时必须同步更新注释（如常量值变化需更新注释描述）。

五、代码结构规范

函数与类

函数代码不超过 200 行，复杂逻辑拆分为子函数（如 “图像增强” 拆为 applyHistogramEqualization()、sharpenImage()、adjustBrightness()）。
函数参数不超过 4 个，超过则用结构体封装（如 struct ImageProcessingParams { int blurKernelSize; double brightnessFactor; };）。
类的成员变量设为 private，通过 getter/setter 访问（需验证逻辑时），避免直接暴露。

控制流

嵌套不超过 3 层（如 if→for→if 可拆分为子函数），优先 “早返回”（如 if (image.empty()) return;）。
避免 goto 语句（仅在异常处理等特殊场景谨慎使用）。

文件组织

每个文件仅含一个核心类 / 功能（如 image_processor.cpp 不包含视频处理逻辑）。
按模块拆分文件（如 “图像滤波模块” 含 filters.h / filters.cpp，“边缘检测模块” 含 edge_detectors.h / edge_detectors.cpp）。

六、语言特性

现代 C++ 特性

优先使用智能指针（std::unique_ptr / std::shared_ptr）管理动态内存，避免裸指针（如 auto imageData = std::make_unique<uchar[]>(width * height);）。
用 std::string 替代 char[]，用 std::vector / std::map 替代原生数组（如 std::vector<cv::KeyPoint> keypoints;）。
常量用 constexpr（编译期常量）或 const（运行期常量），避免 #define（如 constexpr double PI = 3.14159;）。

类型安全

避免隐式类型转换（如 int 转 double 需显式 static_cast<double>(value)）。
用 enum class 替代普通枚举（强类型安全，如 enum class ImageFormat { JPEG, PNG, BMP };）。

异常处理

用 try-catch 捕获异常，避免返回错误码；自定义异常继承 std::exception（如 class ImageLoadError : public std::exception {};）。
异常说明：函数若抛异常需在注释中明确（如 @throw std::runtime_error If image file not found）。

七、质量与安全规范

性能优化

避免重复计算（如循环内的 cv::getTickCount() 移到循环外）。
优先使用 const（如 const cv::Mat& inputImage）减少拷贝，inline 函数优化短函数调用开销。
容器遍历：std::vector 用 for (const auto& elem : vec)，避免下标越界（vec.at(i) 替代 vec[i]，越界抛异常）。

内存安全

禁止内存泄漏：动态内存必须用智能指针或 delete 匹配 new。
避免野指针：指针赋值前判空（如 if (ptr) { /* 操作 */ }），释放后置 nullptr。

错误处理

输入参数校验（如 if (kernelSize % 2 == 0) throw std::invalid_argument("Kernel size must be odd");）。
资源管理：文件 / 网络连接用 RAII（如 cv::VideoCapture cap("video.mp4");，析构自动关闭）。

八、工具与自动化

静态分析：使用 clang-tidy 检测代码问题。
格式化工具：用 ClangFormat 统一代码格式。
单元测试：用 Google Test / Catch2 编写测试用例，覆盖率不低于 **80%**，覆盖边界条件。
版本控制：
- 提交信息用 “类型 + 描述”（如 feat: 增加图像直方图均衡化功能、fix: 修复图像旋转时的内存泄漏）。
- 分支管理：主分支 main（生产）、开发分支 develop，合并前运行测试。

九、关键差异总结（与通用规范对比）

环节	C++ 专项要求	通用原则
命名	宏全大写、枚举强类型（`enum class`）	见名知意、无意义缩写
内存管理	智能指针优先、禁止裸指针泄漏	资源安全、避免冗余
语言特性	`constexpr`、`inline`、RAII 机制	性能与可维护性平衡
错误处理	异常继承 `std::exception`、`try-catch`	明确错误类型、可恢复性
工具	ClangFormat、clang-tidy、Google Test	自动化检测 + 格式化