cpp.mdc

---
description: 
globs: "**/*.c,**/*.cpp,**/*.h,**/*.hpp,**/*.cxx,CMakeLists.txt,*.cmake,conanfile.txt,Makefil,**/*.cc"
alwaysApply: false
---
# C++ 编程指南

## 基本原则

- 所有代码和文档都使用英文。
- 始终声明每个变量和函数（参数和返回值）的类型。
- 创建必要的类型和类。
- 使用 Doxygen 风格的注释来记录公共类和方法。
- 不要在函数内部留空行。
- 遵循单一定义规则 (ODR)。

## 命名法

- 类和结构使用帕斯卡命名法 (PascalCase)。
- 变量、函数和方法使用驼峰命名法 (camelCase)。
- 常量和宏使用全大写 (ALL_CAPS)。
- 文件和目录名使用蛇形命名法 (snake_case)。
- 环境变量使用大写 (UPPERCASE)。
- 避免使用魔术数字并定义常量。
- 每个函数以动词开头。
- 布尔变量使用动词。例如：isLoading, hasError, canDelete 等。
- 使用完整的单词而不是缩写，并确保拼写正确。
  - 标准缩写除外，如 API, URL 等。
  - 众所周知的缩写除外：
    - i, j, k 用于循环
    - err 用于错误
    - ctx 用于上下文
    - req, res 用于请求/响应参数

## 函数

- 编写具有单一目的的短函数。少于 20 条指令。
- 函数命名使用动词和其他词。
- 如果返回布尔值，使用 isX 或 hasX, canX 等。
- 如果不返回任何内容 (void)，使用 executeX 或 saveX 等。
- 通过以下方式避免块嵌套：
  - 提早检查和返回。
  - 提取到实用函数中。
- 使用标准库算法 (std::for_each, std::transform, std::find 等) 来避免函数嵌套。
- 对简单操作使用 lambda 函数。
- 对非简单操作使用命名函数。
- 使用默认参数值，而不是检查 null 或 nullptr。
- 使用结构体或类来减少函数参数
  - 使用对象传递多个参数。
  - 使用对象返回多个结果。

## 错误处理

- 捕获异常的目的应该是：
  - 修复预期的问题。
  - 添加上下文。
  - 否则，使用全局处理器。
- 对预期的失败使用 std::optional, std::expected 或错误码。

## 内存管理

- 优先使用智能指针 (std::unique_ptr, std::shared_ptr) 而不是原始指针。
- 使用 RAII (资源获取即初始化) 原则。
- 通过适当的资源管理避免内存泄漏。
- 使用 std::vector 和其他标准容器，而不是 C 风格的数组。

## 测试

- 测试遵循 Arrange-Act-Assert 约定。
- 清晰地命名测试变量。
- 遵循约定：inputX, mockX, actualX, expectedX 等。
- 为每个公共函数编写单元测试。
- 使用测试替身来模拟依赖项。
  - 执行成本不高的第三方依赖项除外。
- 为每个模块编写集成测试。
- 遵循 Given-When-Then 约定。

## 项目结构

- 使用模块化架构
- 将代码组织到逻辑目录中：
  - include/ 用于头文件
  - src/ 用于源文件
  - test/ 用于测试文件
  - lib/ 用于库
  - doc/ 用于文档
- 使用 CMake 或类似的构建系统。
- 将接口 (.h) 与实现 (.cpp) 分离。
- 使用命名空间来逻辑地组织代码。
- 为基础组件创建一个核心命名空间。
- 为实用函数创建一个 utils 命名空间。

## 标准库

- 尽可能使用 C++ 标准库。
- 优先使用 std::string 而不是 C 风格的字符串。
- 对集合使用 std::vector, std::map, std::unordered_map 等。
- 为现代类型安全使用 std::optional, std::variant, std::any。
- 对文件操作使用 std::filesystem。
- 对时间相关操作使用 std::chrono。

## 并发

- 为线程安全使用 std::thread, std::mutex, std::lock_guard。
- 优先使用基于任务的并行性，而不是基于线程的并行性。
- 对原子操作使用 std::atomic。
- 通过适当的同步避免数据竞争。
- 必要时使用线程安全的数据结构。