@chengzhao-dev/dsh-cpp-workflow 0.6.13 → 0.6.15

package/skills/developing-cpp/steps/03-declaration.md

@@ -6,26 +6,33 @@
 
 ## 通用情况
 
-- 语言标准由项目声明决定，新工程默认 C++23，支持 C++11–C++23；头文件用 `#define` 守卫，名字由源码树全路径生成，不要用 `#pragma once`。槽位与守卫名按 `references/file-template.md`。
-- 命名按 `references/naming.md`：类型与函数 PascalCase，变量与参数 snake_case，类成员尾随 `_`、结构体成员不尾随，常量与枚举子 `k` 前缀。布尔查询与 `Check` 的分工见同文件「谓词与查询命名」。
-- 声明顺序按 `references/declaration-order.md`：类型 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
-- 公共头文件自包含：自身需要的头都直接包含，不依赖调用方的包含顺序。
-- 单参数构造函数写 `explicit`；可查询的成员函数加 `[[nodiscard]]`；默认成员初始化写在声明处，不在构造函数里重复。
-- 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cpp` 定义，模板和 `constexpr` 例外。
-- 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型；越界用 `std::out_of_range`，前置条件被破坏用 `std::logic_error`，只有调用方必须区分时才新增派生类型；Debug/Release 的抛出条件相同。消息句式见 `references/exceptions.md` 的「消息」节。
-- 一次操作有多种必须区分的正常结果时，用 `enum class` 返回（如落子：成功、越界、类型非法、已占），不用 `bool` 把原因压掉；成功还需要附带数据时再考虑 `std::expected` 或结果结构，成功无数据时不用。纯查询谓词仍用 `bool`，不要把 `IsEmpty` 改成三态。
-- 声明注释按 `references/comments.md` 的四节写：写作只写声明里看不出的事实——类型注释的名词短语（纯数据与枚举一句，类只在不变量不重复领域尺寸时加第二段）、特殊成员的标签与后置条件（默认构造只写一行，如 `默认构造函数：格子的初始状态为 kEmpty`）、函数注释的第一句结果或失败方式或检查项与契约。有参数就每个参数一条 `@param`，有返回值默认写 `@return`（成立条件自明时可省），会抛才写 `@throws`；标签与句号规则以 `references/comments.md` 为准，不写空标签。数据成员的主注释放在声明上一行并用 `///`，先说明这个成员是什么，再用全角冒号补名字和类型看不出的轴向、哨兵、所有权与改写时机，行尾不写补充；布局定文件头、位置与行尾；排版定符号、宽度与标签；润色删复述。类型注释不罗列成员功能、不写领域尺寸、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
-- `std::format` 用于组合消息；声明里不要承诺 `std::print`（C++23）。
+- 语言标准由项目声明决定，新工程默认 C++23（C++11–C++23）；`environment.json` 的 `standard` 是唯一来源。
+- 文件槽位、包含守卫与扩展名以 `references/file-template.md` 为准；本步只决定声明写什么。
+- 命名以 `references/naming.md` 为准：规则表、语义角色、谓词与查询命名都在那里。
+- 声明顺序以 `references/declaration-order.md` 为准：类型 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
+- 公共头自包含：自己用到的类型、宏和标准库头都直接包含。
+- 单参数构造函数写 `explicit`；查询成员函数尾部写 `const`；返回结果对象的 API 加 `[[nodiscard]]`，标注位置与 `friend` 的例外见 `references/types.md`；默认成员初始化写在声明处。
+- 头文件只就地定义约 10 行以内的短函数；模板与 `constexpr` 例外，其余函数体在 `.cpp`。
+- 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立不变量时才抛，异常类型的选择与消息见 `references/exceptions.md`。
+- 一次操作有多种必须区分的正常结果时用 `enum class` 返回（如落子：成功、越界、类型非法、已占），不用 `bool` 把原因压掉；成功还要附带数据时再考虑 `std::expected` 或结果结构。纯查询谓词仍用 `bool`。
+- 声明注释按 `references/comments.md` 的四节写：类型注释、特殊成员、函数注释、数据成员。本步只决定「写哪些事实」：结果、失败方式、检查项、参数与返回值契约；句式、标签、宽度和示例由该文件定。
+- 组合消息用 `std::format`；声明里只承诺 `std::format`，`std::print` 是 C++23 的程序边界设施。
 
 ## 情况
 
 **新增类型**：先判断是聚合 `struct`、有不变量的 `class`，还是 `enum class`；接口多于数据且有 invariant 时用 `class`，纯数据传递用 `struct`。
 
-**改公共接口**：先找所有调用方；改签名、改返回类型、改异常声明都算破坏性变更。能加默认参数或重载时优先加，不要静默改变旧调用的含义。
+**改公共接口**：先找所有调用方；改签名、改返回类型、改异常声明都算破坏性变更。能加默认参数或重载时优先加，不静默改变旧调用的含义。
 
-**异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `std::out_of_range`」这样的具体类型，不要只写「可能抛异常」，也不要给每个参数错误都新建类型。类型选择见 `references/exceptions.md`。
+**异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `std::out_of_range`」这样的具体类型，不给每个参数错误新建类型。
 
-**注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的；实现细节留给 `.cpp`。`@param` 每个参数都写，`@return` 每个非 `void` 函数都写，`@throws` 会抛才写；构造、析构与 `void` 无参数函数不写空标签。标识符和标签保持英文。文件头写 `@file`、`@brief` 与一句「包含…」的范围，实现文件可只写前两行；`@file` 必须与文件名相同；作者、日期、版权、版本开关出厂打开，填了非空值才写出。标签开关在插件设置页，技能正文末尾附带当前配置的快照。写完运行 `node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>`；关闭 `@brief` 时加 `--no-brief`，配置里打开了隐私标签并填了值时加 `--allow-tag <标签>`。文件头、标签、参数完整性、成员清单与设计论证由脚本兜底。文件头与 TODO 的格式见 `references/comments.md`。
+**注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的事实，实现细节留给 `.cpp`。文件头、标签、参数完整性与设计论证的规则见 `references/comments.md`。写完运行：
+
+```bash
+node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>
+```
+
+关闭 `@brief` 时加 `--no-brief`；配置里打开了隐私标签并填了值时加 `--allow-tag <标签>`。
 
 ## 正反例指针
 

package/skills/developing-cpp/steps/04-implementation.md

@@ -2,43 +2,43 @@
 
 ## 产出
 
-`.cpp` 实现文件中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明，不新增公共接口。
+`.cpp` 实现文件中的函数体、操作顺序、分组空白和实现注释。实现只兑现第 1 步的行为和第 3 步的声明；需要新增公共接口时回到第 3 步。
 
 ## 通用情况
 
-- 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
-- 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
-- `.cpp` 的第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`；文件槽位见 `references/file-template.md`。
-- `.cpp` / `.cc` 的函数体用 `//`，不用 `///`：体内 `///` 会接到该函数的 Doxygen 详细说明后面。重要函数按空行分阶段，每个阶段上方写一句 `//`，写这一支的后果，可以点明分支处理了哪些枚举值，不把下一行的条件逐词翻译一遍；`//` 里的枚举值不包反引号。`IsFull` 这种单表达式函数不配注释；只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容，变更史留给提交说明。
-- 什么时候在 `if` 上方加一句：多条独立拒绝（`CheckPlaceable`）每个 `if` 一句；成功写入前一句；只有次序依赖的一对 `if` 在第一个上方说明；循环上方已有阶段说明时，循环里的 `if` 不再加，单表达式谓词不加。
-- 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。Debug 与 Release 用同一套返回值与抛出条件，只有诊断详略不同。两种模式都要守的 invariant 用 `Check`（项目保留时），只在开发期做的自检用 `DebugCheck`；没有这两个宏就分别用 `assert` 与 `std::terminate`。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。消息按 `Type::Function: 条件 (值); 限度` 组织，见 `references/exceptions.md` 的「消息」节。
+- 函数保持短小，一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不靠注释把长函数切成几段。
+- 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段。
+- `.cpp` 的第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头，不依赖公共头转发声明。包含顺序见 `references/google-cpp-style.md`，文件槽位见 `references/file-template.md`。
+- 函数体注释用 `//`，不用 `///`：体内 `///` 会接到该函数的 Doxygen 详细说明后面。重要函数按空行分阶段，每个阶段上方写一句 `//`，写这一支的后果，可以点明处理了哪些枚举值，不逐词翻译下一行的条件；`//` 里的枚举值不加反引号。单表达式函数（如 `IsFull`）不配注释。只写删掉会让下一次修改得到错误结果、而代码本身看不出的内容；变更史留给提交说明。
+- 什么时候在 `if` 上方加一句：多条独立拒绝（如 `CheckPlaceable`）每个 `if` 一句；成功写入前一句；只有次序依赖的一对 `if` 在第一个上方说明；循环上方已有阶段说明时，循环里的 `if` 不再加；单表达式谓词不加。
+- 失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。Debug 与 Release 用同一套返回值与抛出条件，只有诊断详略不同。两种模式都要守的不变量用 `Check`（项目保留时），只在开发期做的自检用 `DebugCheck`；项目没有这两个宏时分别用 `assert` 与 `std::terminate`。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。异常类型、消息格式与「不抛的边界」见 `references/exceptions.md`。
 - 声明 `noexcept` 前核对函数体：出现 `at()` 或其他可能抛出的调用就去掉。越界用 `at()` 抛 `std::out_of_range`，这个函数就不能标 `noexcept`。
-- 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
-- 不写 C 风格强制转换；用 `static_cast` / `std::bit_cast` 等具名转换。
+- 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；库实现里不直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
+- 转换用具名转换 `static_cast` / `std::bit_cast`，不用 C 风格强制转换。
 - 所有权用 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。
 - 只改注释时，不改可观察行为；只改实现时，不改公共声明。两者同时需要时，先改声明，再改实现。
-- 清空成员数组：元素类型提供收回空取值的函数时（如 `Cell::Clear`），容器的 `Clear` 逐个调用它；没有这种函数时才用 `std::ranges::fill(cells_ | std::views::join, kEmpty)` 或 `for` 循环逐格赋空值。两种都不写 `cells_ = {}`，也不从外面把枚举赋成空值。
+- 清空成员数组：元素类型提供收回空取值的函数时（如 `Cell::Clear`），容器的 `Clear` 逐个调用它；没有这种函数时才用 `std::ranges::fill(cells_ | std::views::join, CellState::kEmpty)` 或 `for` 循环逐格赋空值。两种写法都不直接写 `cells_ = {}`，也不从外部把枚举赋成空值。
 - 默认构造只做「建立初值」时用成员初值（如 `cells_{}`），不在构造函数里再调一遍 `Clear()`；`Clear()` 只负责把已经写入的元素收回空。
 
 ## 情况
 
-**新实现**：先写最短的直路，让第 1 步的验收通过；重复出现两次以上再抽函数。不要预埋未使用的抽象。
+**新实现**：先写最短的直路，让第 1 步的验收通过；同样的代码重复出现两次以上再抽函数，不预埋未使用的抽象。
 
 **修缺陷**：先加一个能复现的测试或最小输入，再改实现；修完删掉临时调试输出，保留测试。
 
-**重构**：一次只动一种东西（改名、抽函数、换容器）。每步都让测试保持绿色；行为句不变。
+**重构**：一次只动一种东西（改名、抽函数、换容器），每步都让测试保持绿色，行为句不变。
 
-**异常边界**：库内部让异常向上传播；程序入口捕获 `std::exception`（或项目自己的异常基类），用 `std::format("错误: {}", error.what())` 打印，返回项目约定的非零退出码。不要吞掉异常后继续用无效状态。
+**异常边界**：库内部让异常向上传播；程序入口捕获 `std::exception`（或项目自己的异常基类），用 `std::format("错误: {}", error.what())` 打印，返回项目约定的非零退出码。不吞掉异常后继续使用无效状态。
 
 ## 交回构建
 
-要补测试、新增或移动源文件时，交给 `building-cpp` 的定构建：把文件显式写进 CMake，再决定是否定工具配置，最后通过检查。不要只改完函数体就宣称完成。
+实现改完，按顺序交给下游：需要新增或移动源文件时，先由 `configuring-cmake` 的 `steps/01-targets.md` 把文件显式写进 target；target 齐了再由 `building-cpp` 的 `steps/01-build.md` configure、构建，最后走 `steps/03-check.md`。不要只改完函数体就宣称完成。
 
 ## 正反例指针
 
 - 实现注释复述代码、分组混乱：`examples/comments-implementation.md`「实现注释」。
-- 已经证明非负的坐标把下标收成 `std::size_t` 再 `[]`，不要转成 `int`：`references/types.md`「下标与越界」。
-- 越界消息的标签取自调用点：`references/exceptions.md`「消息」的 `std::source_location` 一句。
+- 已经证明非负的坐标把下标收成 `std::size_t` 再 `[]`，不转成 `int`：`references/types.md`「下标与越界」。
+- 越界消息的标签取自调用点：`references/exceptions.md`「消息」的 `std::source_location` 用法。
 - 为了保住 `noexcept` 再包一层只转发下标的私有函数：`references/exceptions.md`「不抛的边界」。
 - 异常类型与结果类型混用：`examples/exceptions.md`「什么时候抛」。
 - `std::format` 与流输出混用得当：`examples/exceptions.md`「异常类型与消息」。