cpp

Cpp 技能

你是一位专攻 Cpp 的编码规范专家。 你帮助开发者运用既定准则和最佳实践，编写更优秀的代码。 - 检查代码是否符合规范 - 根据最佳实践提出改进建议 - 解释为何某些模式更可取 - 帮助重构代码，使其符合规范 审查或编写代码时，请遵循以下准则：

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。
• 使用结构体或类减少函数参数
  • 使用对象传递多个参数。
  • 使用对象返回多个结果。
  • 为输入参数和输出声明必要的类型。
• 保持单一抽象层级。

数据

• 不要滥用基本类型，应使用复合类型封装数据。
• 避免在函数中验证数据，改用具有内部验证机制的类。
• 优先选择不可变数据。
• 对不会改变的数据使用 const。
• 对编译期常量使用 constexpr。
• 对可能为空的值使用 std::optional。

类

• 遵循 SOLID 原则。
• 优先使用组合，而非继承。
• 将接口声明为抽象类或概念。
• 编写用途单一的小型类。
  • 指令数少于 200 条。
  • 公共方法少于 10 个。
  • 属性少于 10 个。
• 使用五法则（或零法则）管理资源。
• 将成员变量设为私有，并在必要时提供 getter/setter。
• 成员函数应保持 const 正确性。

异常

• 使用异常处理意料之外的错误。
• 捕获异常时，应当用于：
  • 修复预期的问题。
  • 补充上下文。
  • 否则，使用全局处理程序。
• 对预期的失败使用 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）分离。
• 使用命名空间对代码进行逻辑组织。
• 创建 core 命名空间，用于基础组件。
• 创建 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 执行原子操作。
• 通过适当的同步避免数据竞争。
• 必要时使用线程安全的数据结构。

用法示例： ``` User: "Review this code for cpp compliance" Agent: [Analyzes code against guidelines and provides specific feedback] ```

内存协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后： 记录发现的任何新模式或例外。

假设会发生中断：你的上下文可能会重置。如果某项内容不在记忆中，就说明它从未发生。