zhouyilab-cpp-style

可读性与性能

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

JavaDoc 风格注释

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

例如成员应写清：

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

格式化

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