---
name: zhouyilab-cpp-style
description: 编写 ZhouYiLab C++ 代码时落实性能、命名、枚举定义、成员注释和 WSL clang-format 规范。
---

## 可读性与性能

- 性能与代码美感优先，但以正确性和清晰边界为前提。固定小域优先数组、枚举与只读定义表；已知数量的结果预留容量，避免循环中重复构建映射、重复查根和拼接无用字符串。
- 私有规则表和辅助函数放 `.cpp`，必要时使用匿名命名空间。仅在真实热点或稳定不变量处缓存；不要引入无界全局缓存、悬空 `string_view` 或为“零拷贝”破坏生命周期。
- 规则用稳定枚举/规则标识作键，不用散落的中文字符串驱动分支。显示名称复用 `ZhouYi.ZhMapper` 及所属领域映射，不另造通用枚举反射库。
- 文件名采用现有 `snake_case`，模块名沿用 `ZhouYi.*`；专业概念命名为排盘、原局、课体、卦象等对应语义，禁止泛称“事实层/事实项/事实依据”及含混的 `misc/partN` 拆分。

## JavaDoc 风格注释

- 修改或新增的公共 enum、每个枚举值、struct/class、每个成员及公开函数均补中文 `/** ... */` 注释。字段说明含义、单位/范围、默认值语义；可选项说明未提供如何处理，数值区分分值、比例、规则权重。
- 函数用 `@brief`、`@param`、必要的 `@tparam`、`@return`、`@throws` 说明契约；不要机械为 void 写返回值或声称不会发生的异常。私有复杂公式说明依据、边界与不变量，简单语句不逐行翻译。
- 接口保留完整契约注释，实现只解释推演和算法原因。移动函数/枚举/结构时注释一起移动，不以格式化或拆文件为由丢弃注释。

例如成员应写清：

```cpp
/** @brief 是否完成三合三支补齐；不代表已经成化。 */
bool complete = false;
/** @brief 关系作用系数，范围 [0, 1]；0 表示该作用未计入。 */
double effectiveness = 0.0;
```

## 格式化

- 先查实际可用的 WSL 发行版与 `clang-format` 版本，再使用 WSL 的 Clang 格式化工具处理本次修改的 `.cppm`、`.cpp`；若不可用，说明未格式化，不假称已执行。
- 优先遵循仓库已有格式配置，无配置则延续邻近代码风格。只格式化本次相关文件，不顺手重排整个仓库或第三方库。
- 格式化后检查 `git diff --check` 与差异，确认中文编码、注释、模块声明及公共签名未受损。