C++ 代码规范文章

一、通用核心原则

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

二、命名规范

三、代码格式规范

缩进与换行

• 统一用 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，合并前运行测试。

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