@chengzhao-dev/dsh-cpp-workflow 0.3.0 → 0.5.0

package/skills/developing-cpp/examples/comments.md

@@ -5,258 +5,295 @@
 **差**：
 
 ```cpp
-// task_list.cc
-// 作者：张三
-// 创建：2024-01-01
-// 修改：2024-02-01 修复 bug
+// board.h
+// 作者：chengzhao-dev
+// 创建：2026-01-01
+// 修改：2026-03-02 增加 CompletesLine
 ```
 
 **好**：
 
 ```cpp
 //===----------------------------------------------------------------------===//
-// TaskList 的存储、优先级排序与稳定顺序。
+// board.h - 定义井字棋棋盘。
 //
-// 不处理终端输入输出；程序层负责解析「优先级 名称」并打印。
+// 棋盘只保存格子状态与规则判断，不含对局流程；对局流程在 game.h。
 //===----------------------------------------------------------------------===//
 ```
 
-文件头回答「这个文件负责什么、不负责什么」，不写作者和变更史。
+文件头回答「这个文件负责什么、不负责什么」，不写作者和变更史。后两行是这条边界：读的人由此知道该去哪个文件找回合推进。
 
-## 声明注释
+## 类型注释：概念与约定，不是功能清单
 
 **差**：
 
 ```cpp
-/// 获取任务。
-/// @param index 索引
-/// @return 任务
-Task GetTask(int index) const;
+/// 井字棋棋盘。
+///
+/// 提供检查坐标区间、检查棋盘格子是否为空、获取棋盘格子类型、放置棋子、清空棋盘和判定终局的功能。
+/// 棋盘为 3 行 3 列。
+class Board {
 ```
 
-问题：没说越界行为，没说返回的是拷贝还是引用。
+问题有两处：把成员函数抄了一遍，接口一改就过期；「棋盘为 3 行 3 列」被拆成单独一句，读者不知道它在回答什么问题。
 
-**好**：
+**差**（把别的类型和以后才发生的事都写进来）：
 
 ```cpp
-/// 返回 index 处的任务副本。
+/// 井字棋棋盘。
 ///
-/// @param index 任务下标，必须在 [0, tasks_.size()) 内
-/// @return 该位置的任务
-/// @throws TaskIndexError index 越界
-[[nodiscard]] Task GetTask(int index) const;
+/// 棋盘只保存 3×3 的格子状态和规则判断，不含回合推进：谁该落子、落子被拒后怎么提示留在 Game。
+///
+/// 棋盘是值语义，可以自由拷贝；所有查询都是 const，对局和搜索可以交替读取同一棋盘。
+class Board {
 ```
 
-契约完整：范围、返回、异常声明。
+第二段说的是 `Game` 负责什么，读者读完仍不知道 `Board` 保证什么，重构一次这句话就过期；后两段里的可拷贝、`const` 查询在类声明里已经写清，「搜索要读同一棋盘」还不是现在的调用方。读者真正需要的是这个类型自己的不变量与失败方式。
 
-## 实现注释
-
-**差**：
+**好**：
 
 ```cpp
-// 如果 tasks_ 为空
-if (tasks_.empty()) {
-  // 返回空
-  return {};
-}
-// 遍历 tasks_
-for (const auto& task : tasks_) {
-  // 比较优先级
-  if (task.priority < best.priority) {
-    // 更新 best
-    best = task;
-  }
-}
+/// 井字棋棋盘。
+///
+/// 3×3 个格子，每格取空、X 或 O；越界坐标不会写入棋盘。
+class Board {
 ```
 
-每行都在复述代码。
+两句都是本类型能兑现、读代码又不容易一眼看全的事，函数各自的契约下沉到函数注释；设计理由与分层不写进注释，写进书稿。
 
-**好**：
+## 风格理由不进注释
+
+**差**（在十几个函数上各写一遍）：
 
 ```cpp
-// 空列表是合法状态，调用方不应被迫先判空。
-if (tasks_.empty()) {
-  return {};
-}
+/// 检查坐标是否在范围内。函数名用 UpperCamel 而不是 snake_case，与标准库区分。
+[[nodiscard]] static bool IsInRange(CellPosition position) noexcept;
 
-// 优先级相同时保留先加入的任务：用严格小于，不交换等值元素。
-for (const auto& task : tasks_) {
-  if (task.priority < best.priority) {
-    best = task;
-  }
-}
+/// 检查格子是否为空。函数名用 UpperCamel 而不是 snake_case，与标准库区分。
+[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
 ```
 
-解释「为什么」和「稳定排序的取舍」，不翻译语句。
+**好**（只写契约）：
 
-## TODO
+```cpp
+/// 检查坐标是否落在棋盘下标区间内。
+///
+/// 只判断几何边界，不检查格子是否为空、对局是否已经结束。
+[[nodiscard]] static bool IsInRange(CellPosition position) noexcept;
+```
+
+命名与风格约定写进项目文档和读者正文，注释里不解释「为什么用这种命名」。
+
+## 第一句：先写结果或限制
 
 **差**：
 
 ```cpp
-// TODO: 参考 xxx
-// FIXME: 这里可能有问题
-// TODO(张三): 优化
+/// 检查坐标。
+/// 返回格子类型；越界会抛异常。
+CellType GetCellType(CellPosition position) const;
 ```
 
+前两句都没有直接回答“合法时拿到什么、越界时发生什么”，读者要读完三句才拼出合同。
+
 **好**：
 
 ```cpp
-// TODO: 阶段 2 - 支持按截止日期排序
-// TODO: issue #42 - 把优先级解析抽成 TryParsePriority
+/// 坐标越界时抛出 std::out_of_range；合法坐标返回该格类型。
+///
+/// @param position 行列坐标。
+/// @throws std::out_of_range 坐标不在棋盘范围内。
+CellType GetCellType(CellPosition position) const;
 ```
 
-有定位、有动作、能搜索。
+第一句就是结果或失败方式；后面的标签只补参数与异常细节，不再重复这句话。
 
-## 配置注释
+## 函数契约
 
 **差**：
 
-```yaml
-# 这是 clang-format 配置
-# 详见某文档
-ColumnLimit: 100
+```cpp
+/// 尝试执行一次落子。
+///
+/// @param move 落子。
+/// @returns 落子执行成功返回 kPlaced，被拒绝返回 kRejected。
+[[nodiscard]] PlaceResult TryPlace(const Move& move);
 ```
 
+`@param move 落子` 是把类型名翻译成中文，没有信息；`@returns` 不是 Doxygen 标签；没有说被拒绝的条件，调用方只能读实现。
+
 **好**：
 
-```yaml
-# 列宽、缩进、包含顺序都取 Google 预设，不逐项覆盖。
-Language: Cpp
-BasedOnStyle: Google
-Standard: Latest
+```cpp
+/// 尝试执行一次落子。
+///
+/// 只有本局仍在进行、且落子玩家正是当前玩家时才继续，棋盘、轮次、历史三者一起更新。
+///
+/// @param move 待执行的落子，玩家必须是当前轮到的玩家。
+/// @return 落子写入棋盘并换手时返回 kPlaced；对局已结束或上述任一条件不满足时返回 kRejected，
+///         棋盘和轮次都不变。
+[[nodiscard]] PlaceResult TryPlace(const Move& move);
 ```
 
-解释为什么选预设，不写策略头，不指文档路径。
-
-## 横幅
+## 布尔查询要写「不检查什么」
 
 **差**：
 
 ```cpp
-// ===== 函数 =====
-void AddTask();
-void RemoveTask();
-// ===== 结束 =====
+/// 检查指定坐标上的棋盘格子是否为空。
+[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
 ```
 
 **好**：
 
 ```cpp
-//===----------------------------------------------------------------------===//
-// 查询
-//===----------------------------------------------------------------------===//
-
-[[nodiscard]] std::size_t Size() const;
-[[nodiscard]] bool IsEmpty() const;
+/// 检查指定坐标上的棋盘格子是否为空。
+///
+/// 只回答「这一格能不能落子」，不判断对局是否已经结束：对局结束后格子仍是空的，
+/// 但再落子没有意义。是否需要先看对局状态由调用方决定，棋盘不替它下结论。
+///
+/// @param position 待检查的坐标。
+/// @return 坐标在棋盘内且该格为空时返回 true；越界或该格已有棋子时返回 false。
+[[nodiscard]] bool IsCellEmpty(CellPosition position) const;
 ```
 
-横幅是跳转锚点，不是装饰；一组函数一个横幅，单函数不加。
+布尔函数最容易被误用；把「不检查什么」写出来，比多写一个参数说明有用。
 
-## 枚举行尾注释
+## 枚举
 
 **差**：
 
 ```cpp
-enum class TaskStatus : std::uint8_t {
-  kPending,  // 待处理
-  kActive,   // 处理中
-  kBlocked,  // 等待外部输入
-  kDone      // 已完成
+enum class Player : std::uint8_t {
+  kCross,  // X
+  kNought  // O
 };
 ```
 
-问题：四个成员都写等于没写，且把名字重复了一遍。
-
 **好**：
 
 ```cpp
-enum class TaskStatus : std::uint8_t {
-  kPending,  ///< 已登记，尚未开始
-  kActive,   ///< 正在处理
-  kBlocked,  ///< 等待外部输入，不能继续
-  kDone      ///< 已完成，不再改动
+/// 对局结果。
+enum class GameResult : std::uint8_t {
+  kInProgress = 0,  ///< 游戏进行中：还可以落子。
+  kCrossWin = 1,    ///< X 获胜：达成三连。
+  kNoughtWin = 2,   ///< O 获胜：达成三连。
+  kDraw = 3,        ///< 平局：棋盘已满，双方都没有三连。
 };
 ```
 
-若只有部分成员需要解释，同一枚举内要写就写全，或全不写；不要半套。语义结果写在最前，判定条件放冒号后。
+行尾注释先写语义，需要时用冒号补一句能核实的条件或结果，两段都短；不重复名字，不写嵌套子句，同一枚举要么全写要么全不写。
 
-## 声明注释的完整契约
+## 数据成员
 
 **差**：
 
 ```cpp
-/// 修改任务优先级。
-/// @param id 任务编号
-/// @param priority 优先级
-void SetPriority(TaskId id, int priority);
+Board board_;
+Player current_player_;
+GameResult result_;
 ```
 
 **好**：
 
 ```cpp
-/// 修改任务优先级。
-///
-/// @param id 任务编号，必须已存在
-/// @param priority 新优先级，必须在 [0, 9] 内
-/// @throws TaskIndexError 编号不在当前任务表内
-/// @throws InvalidPriorityError priority 越界
-void SetPriority(TaskId id, int priority);
+Board board_;                             // 对局棋盘。
+Player current_player_ = Player::kCross;  // 当前轮到的玩家，开局时 X 先手。
+GameResult result_ = GameResult::kInProgress;  // 对局结果；落子被拒时不改写。
 ```
 
-只写调用者无法从签名推出来的内容：范围、所有权、失败方式。`@brief` 不写，第一行就是摘要。
+行尾写「存什么 + 初值含义 + 什么时候变」，同类成员对齐。
 
-## 相邻注释
+## 实现注释
 
 **差**：
 
 ```cpp
-// 这里先检查存在性
-// 然后检查状态
-// 最后写入
-if (!Contains(id)) return false;
-if (tasks_[Index(id)].status == TaskStatus::kDone) return false;
-tasks_[Index(id)].status = TaskStatus::kActive;
-return true;
+// 遍历所有空格
+for (const auto& position : empty_cells) {
+  // 尝试落子
+  const bool wins = game.Board().CompletesLine(position, cell_type);
+  // 如果能赢
+  if (wins) {
+    // 返回这一手
+    return position;
+  }
+}
 ```
 
+每行都在复述代码。
+
 **好**：
 
 ```cpp
-// 先检查再写入：失败时不留下半完成状态。
-if (!Contains(id)) return false;
-if (tasks_[Index(id)].status == TaskStatus::kDone) return false;
-tasks_[Index(id)].status = TaskStatus::kActive;
-return true;
+// 先找能立刻赢的格子：启发式只在「马上赢」和「马上挡」之间做选择，
+// 不在这里做更深的前瞻，深搜留给 MinimaxAi。
+for (const auto& position : empty_cells) {
+  if (game.CompletesLine(position, CellType::kX)) {
+    return position;
+  }
+}
 ```
 
-一段连续的实现注释只讲一个判断或一个取舍；不是逐行字幕。
+解释「为什么停在这一层」，不翻译语句。
 
-## 成员还是同一命名空间的函数
+## TODO
 
 **差**：
 
 ```cpp
-class TaskTable {
- public:
-  std::size_t CountOverdue() const;
-  bool HasOverdue() const { return CountOverdue() > 0; }
-};
+// TODO: 参考 xxx
+// FIXME: 这里可能有问题
 ```
 
-`HasOverdue` 只组合公开查询，不需要直接访问表示，却做成了成员。
+**好**：
+
+```cpp
+// TODO: 阶段 5 - 给 MinimaxAi 加置换表，减少重复局面的搜索。
+```
+
+有定位、有动作、能搜索。
+
+## 配置注释
+
+**差**：
+
+```yaml
+# 这是 clang-format 配置
+# 详见某文档
+ColumnLimit: 100
+```
 
 **好**：
 
+```yaml
+# 列宽、缩进、包含顺序都取 Google 预设，不逐项覆盖。
+Language: Cpp
+BasedOnStyle: Google
+Standard: Latest
+```
+
+解释为什么选预设，不写策略头，不指文档路径。
+
+## 不该进注释的东西
+
+**差**：
+
 ```cpp
-class TaskTable {
- public:
-  std::size_t CountOverdue() const;
-};
+// 2026-03-02 把 Board 从 Game 里拆出来，因为之前 Game 太长。
+// 参见 https://example.com/2026/03/02/refactor
+// 其余成员见下方注释，两处不重复。
+// 本团队要求所有类注释写满五行。
+```
 
-bool HasOverdue(const TaskTable& table) {
-  return table.CountOverdue() > 0;
-}
+**好**：
+
+```cpp
+//===----------------------------------------------------------------------===//
+// board.h - 棋盘状态与规则判断
+//
+// 这一层只有格子状态和胜负判定；回合推进在 game.h，输入输出在 apps/。
+//===----------------------------------------------------------------------===//
 ```
 
-函数和类放在同一命名空间；调用方只看到 `HasOverdue(table)`，类不增加只为转发而存在的成员。
+变更史进提交说明，外部资料进文档，团队流程进规范文件，跨文件的边界写文件头；类注释只写本类型自己的契约。

package/skills/developing-cpp/examples/exceptions.md

@@ -22,11 +22,11 @@ struct ParseResult {
 
 [[nodiscard]] ParseResult TryParseTask(std::string_view line);
 
-/// @throws TaskIndexError index 不在 [0, size()) 内。
+/// @throws std::out_of_range index 不在 [0, size()) 内。
 [[nodiscard]] Task GetTask(int index) const;
 ```
 
-`TryParseTask` 把失败作为正常结果返回。`GetTask` 的前提是调用方给出有效下标；下标无效时函数无法返回一个任务，于是抛出带领域语义的 `TaskIndexError`。如果越界其实是正常输入，应该改成返回 `std::optional<Task>`，而不是让调用方捕获异常。
+`TryParseTask` 把失败作为正常结果返回。`GetTask` 的前提是调用方给出有效下标；越界时函数无法返回一个任务，抛标准库已有的 `std::out_of_range`。如果越界其实是正常输入，应该改成返回 `std::optional<Task>`，而不是让调用方捕获异常；只有项目需要把这种越界和别处的 `out_of_range` 区分开时，才定义派生类。
 
 ## 异常类型与消息
 
@@ -36,34 +36,53 @@ struct ParseResult {
 throw "bad index";
 ```
 
-**好**：定义有语义的类型；确实没有更多信息时，才直接用标准库通用类型。
+**好**：语义已经由标准类型给出时直接用标准类型；需要额外携带领域信息时，再派生自它。
 
 ```cpp
-class TaskIndexError : public std::out_of_range {
- public:
-  explicit TaskIndexError(const std::string& message)
-      : std::out_of_range(message) {}
-};
-
-throw TaskIndexError{
+throw std::out_of_range{
     std::format("GetTask: index={} 超出 [0, {})", index, tasks_.size())};
 ```
 
-消息写操作和关键值，不写「出错了」；`std::format` 只是构造消息的方式，不强制固定模板。
+消息写操作和关键值，不写「出错了」；`std::format` 只是构造消息的方式，不强制固定模板。项目若定义 `Error` 基类，按 `references/exceptions.md` 先定基类再派生，调用方捕获基类接住整族。
+
+## Debug 与 Release 的三层合同
+
+**差**：同一个函数在 Debug 抛异常、在 Release 返回 false；调用方被迫按构建模式写两套分支。
+
+```cpp
+#ifdef NDEBUG
+return false;
+#else
+throw std::out_of_range{row, col};
+#endif
+```
+
+**好**：返回值在两种模式完全一致；需要异常时两种模式都抛，只有 `what()` 的详略不同。
 
-## 多语义类型：Boost.Exception 风格
+```cpp
+// 返回值：失败是可恢复结果，两种模式都返回 false。
+[[nodiscard]] bool TryPlace(CellPosition position, Player player) noexcept;
+
+// 越界：两种模式都抛 std::out_of_range；Debug 消息可带 file:line。
+void Place(CellPosition position, Player player);
+```
+
+越界用标准库已有的 `std::out_of_range`，调用方不需要认识项目私有类型；只有调用方必须把它和其它 `out_of_range` 区分开时，才定义派生类并在 `what()` 里补位置信息。
+
+**差**：用 `assert` 承担 Release 也必须执行的 invariant 检查；`NDEBUG` 后检查消失。
+
+```cpp
+assert(game.GetResult() == GameResult::kInProgress);
+```
 
-一个错误可以同时属于多个类别。类型只做 `catch` 的标签，数据由基类或错误信息容器携带；多继承时用 virtual 基类，避免 `catch (const std::exception&)` 二义性。
+**好**：两种模式都必须检查的 invariant 用 `Check`（项目保留时），失败时打印诊断并终止；只在开发期值得做、Release 可以省掉的自检用 `DebugCheck`。没有这两个宏时分别用 `assert` 与 `std::terminate`。
 
 ```cpp
-struct exception_base : virtual std::exception, virtual boost::exception {};
-struct io_error : virtual exception_base {};
-struct file_error : virtual io_error {};
-struct read_error : virtual io_error {};
-struct file_read_error : virtual file_error, virtual read_error {};
+Check(game.GetResult() == GameResult::kInProgress, "Ai::Choose: game is already over");
+DebugCheck(index < history_.size(), "history index out of range");
 ```
 
-这只是设计典范，不要求引入 Boost。项目自己的异常层级也可以照这个形状写。
+`Check` 不是 `[[noreturn]]`：条件成立时正常返回。`DebugCheck` 在 `NDEBUG` 后展开为空，参数不能带副作用。
 
 ## 捕获
 

package/skills/developing-cpp/examples/structure.md

@@ -20,7 +20,7 @@
 **差**：库函数直接打印，程序只调用它。
 
 ```cpp
-// task_list.cc（库）
+// task_list.cpp（库）
 void TaskList::Print() const {
   for (const auto& task : tasks_) {
     std::cout << task.priority << " " << task.name << "\n";
@@ -36,7 +36,7 @@ void TaskList::Print() const {
 // task_list.h（库）
 [[nodiscard]] std::vector<Task> SortedByPriority() const;
 
-// app/cli.cc（程序）
+// app/cli.cpp（程序）
 void PrintTasks(const std::vector<Task>& tasks, std::ostream& out) {
   for (const auto& task : tasks) {
     out << std::format("{} {}\n", task.priority, task.name);
@@ -63,7 +63,7 @@ src/detail.h                     // 私有头被测试直接包含
 
 ```text
 task_list/include/task_list.h    // 公共头
-task_list/src/task_list.cc       // 实现
+task_list/src/task_list.cpp       // 实现
 task_list/src/detail.h           // 私有头，只被本组件包含
 ```
 
@@ -75,8 +75,79 @@ task_list/src/detail.h           // 私有头，只被本组件包含
 
 ## 单文件何时拆库
 
-**先不拆**：一个 `main.cc`，辅助函数在匿名命名空间，只有程序自己用。
+**先不拆**：一个 `main.cpp`，辅助函数在匿名命名空间，只有程序自己用。
 
 **该拆**：测试需要直接调用排序逻辑；或第二个程序要复用同一逻辑；或逻辑已经超过一个屏幕。
 
 拆的时候先定公共头（只暴露 `SortedByPriority`），把实现移到 `src/`，行为句不变，测试先绿再改构建。
+
+## 固定坐标用表
+
+**差**：每次判断成线，都用循环把八条线的坐标重新拼一遍；行、列、对角线混在一个循环里，读者要跟着跑两遍才知道哪八条。
+
+```cpp
+// 差：用循环现写八条线，坐标藏在控制流里。
+std::vector<std::vector<CellPosition>> BuildLines() {
+  std::vector<std::vector<CellPosition>> lines;
+  for (int row = 0; row < kRows; ++row) { /* ... */ }
+  // 列与两条对角线再各写一段
+  return lines;
+}
+```
+
+**好**：固定坐标写成匿名命名空间里的常量表，`HasLine` 与 `IsLineComplete` 共用；格子用 `[]`，整条线 `all_of`、八条线 `any_of`。
+
+```cpp
+// board.cpp 的匿名命名空间：行、列、对角线三组，坐标固定。
+constexpr std::array<std::array<CellPosition, 3>, 8> kLines{{
+    {{{0, 0}, {0, 1}, {0, 2}}},  // 行 0
+    {{{1, 0}, {1, 1}, {1, 2}}},  // 行 1
+    {{{2, 0}, {2, 1}, {2, 2}}},  // 行 2
+    {{{0, 0}, {1, 0}, {2, 0}}},  // 列 0
+    {{{0, 1}, {1, 1}, {2, 1}}},  // 列 1
+    {{{0, 2}, {1, 2}, {2, 2}}},  // 列 2
+    {{{0, 0}, {1, 1}, {2, 2}}},  // 对角线
+    {{{0, 2}, {1, 1}, {2, 0}}},  // 反对角线
+}};
+```
+
+每个格子要分别处理时仍写 `row` / `col` 循环，例如收集空格、终端打印。
+
+## 推演一步读原数据
+
+**差**：先复制整盘，再在副本上落子，最后判断成线；调用方看不出副本只是中间量。
+
+```cpp
+Board hypothetical = *this;
+hypothetical.PlaceCell(position, cell_type);
+return hypothetical.HasLine(cell_type);
+```
+
+**好**：判断「这一格换成某种棋子后会不会成线」不需要第二份棋盘。越界、空格、已占用仍按 `PlaceCell` 的拒绝条件返回 `false`；通过之后只在包含该坐标的线上把这一格算作 `cell_type`，其余格子读原棋盘。
+
+```cpp
+bool Board::IsLineComplete(CellPosition position, CellType cell_type) const noexcept {
+  if (!IsInRange(position) || cell_type == CellType::kEmpty) {
+    return false;
+  }
+  if (cells_[position.row][position.col] != CellType::kEmpty) {
+    return false;
+  }
+
+  const auto matches = [&](CellPosition cell) {
+    if (cell.row == position.row && cell.col == position.col) {
+      return true;
+    }
+    return cells_[cell.row][cell.col] == cell_type;
+  };
+
+  return std::ranges::any_of(kLines, [&](const auto& line) {
+    const bool contains = std::ranges::find_if(line, [&](CellPosition cell) {
+                            return cell.row == position.row && cell.col == position.col;
+                          }) != line.end();
+    return contains && std::ranges::all_of(line, matches);
+  });
+}
+```
+
+只用 `[]` 与 `IsInRange`，不调用 `at()`，头文件上的 `noexcept` 可以留下；原棋盘不被写入。