@chengzhao-dev/dsh-cpp-workflow 0.6.9 → 0.6.10

package/README.en.md

@@ -19,13 +19,13 @@ The exception material follows the C++ Core Guidelines' Error handling section a
 Pinned npm install:
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.9
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.10
 ```
 
 The matching Git tag:
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.9
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.10
 ```
 
 The desktop app owns the `desktop` profile. If the command-line `add` is rejected, add the plugin in the app settings and use the same pinned npm version. A Git tag install uses the prebuilt `lib/` committed in the repository and runs no build on the target machine; the package has no install script that needs approval.

package/README.md

@@ -19,13 +19,13 @@
 npm 安装钉死版本：
 
 ```bash
-dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.9
+dsh plugin --profile web add npm:@chengzhao-dev/dsh-cpp-workflow@0.6.10
 ```
 
 同版本的 Git 标签：
 
 ```bash
-dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.9
+dsh plugin --profile web add github:chengzhao-dev/dsh-cpp-workflow#v0.6.10
 ```
 
 桌面应用独占 `desktop` profile。命令行 `add` 被拒绝时，在应用设置里添加插件，地址填同一个 npm 版本。Git 标签安装使用仓库内已构建的 `lib/`，不在目标机器上重新构建；包内也不含需要授权执行的安装脚本。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chengzhao-dev/dsh-cpp-workflow",
-  "version": "0.6.9",
+  "version": "0.6.10",
   "description": "写 C++ 源码、配 CMake、用 Clang 构建；头文件用 /// Doxygen 文档注释，函数体用 // 分段说明，文件头标签可在设置里改。",
   "type": "module",
   "main": "./lib/index.js",

package/skills/developing-cpp/references/declaration-order.md

@@ -41,6 +41,14 @@ class TaskTable {
 - 用户声明的特殊成员函数集中放第 4 组；`= default` 也写出来，读者才知道是故意默认。
 - 不要把数据成员插在函数之间；数据成员永远在最后一组。
 
+### 其他函数的组内次序
+
+Google、LLVM、OpenCV 都没有规定这一组内部的次序；本工作流补上：
+
+- 谓词 `Is` / `Has` / `Can`，然后 `Get`，然后普通函数按使用先后，最后是 `friend` 函数。
+- `friend` 不放在这一组开头，也不单放在类的最前面，不强制放进 `private`。
+- `friend` 类型仍跟其他类型放在一起，和 `friend` 函数不是同一组。
+
 ## 命名空间作用域的头文件
 
 文件槽位与守卫名以 `references/file-template.md` 为准；本节只看命名空间作用域内的排列顺序。

package/skills/developing-cpp/references/google-cpp-style.md

@@ -54,7 +54,7 @@
 - 默认用花括号初始化：`int count{};`、`std::vector<int> values{1, 2, 3};`。只有需要对比、`auto` 推导或赋值语义时用 `=`；`name = {{` 只用于多行聚合常量表，单个对象和空初始化仍写 `count{}`；不要用 `()` 初始化普通对象。
 - 类声明顺序：public → protected → private；类型与别名 → 静态常量 → 工厂 → 构造/赋值/析构 → 其他函数 → 数据成员。
 - 用户声明的拷贝/移动/析构函数在头文件声明、在 `.cpp` 定义；只有零参数且默认实现足够时才写 `= default`。
-- 查询成员函数标尾部 `const`；返回结果对象的 API 加 `[[nodiscard]]`，不要给所有非 `void` 函数机械添加。
+- 查询成员函数标尾部 `const`；返回结果对象的 API 加 `[[nodiscard]]`，不要给所有非 `void` 函数机械添加。标注位置与 `friend` 的例外见 `references/types.md`「`[[nodiscard]]`」。
 - 所有权优先 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。禁止裸 `new` / `delete`。
 - 禁止 C 风格强制转换；用 `static_cast`、`const_cast`、`reinterpret_cast`、`std::bit_cast`，并让 `clang-tidy` 的 `google-readability-casting` 兜底。
 - `.cpp` 里不需要外部引用的 `constexpr` 直接放具名命名空间；仅一个函数使用时才用函数内 `static constexpr`；函数和类型仍放匿名命名空间。

package/skills/developing-cpp/references/project-design.md

@@ -18,6 +18,15 @@
 - 同一底层类型承载不同含义（米/秒、行/列）且容易混用时，用轻量强类型包装。
 - 不为每个名词造类；只有出现行为、不变量或独立变化原因时才升级为 `class`。
 
+### 取值的边界
+
+- 封闭取值一次列全。格子的取值是空、X、O；不要把 X 和 O 做成不含空的棋子，再用空值表示空格。
+- 位置是行和列，不是格子的另一种取值。胜负、轮到谁、已下过的序列属于棋盘或对局，不要塞进位置类型。
+- 有不变量的格子用公开构造的类，默认是空，X 或 O 至多写入一次。私有构造函数只留给必须经过工厂才能建立的对象，不用来表达三种取值，也不用来藏起行和列。
+- 一次写入能区分的失败都放进结果枚举。传入空取值是结果项，不抛异常。
+- 只由某一个类型产生的结果枚举嵌在该类型里：格子的写入结果和对局的写入结果取值不同，不合成命名空间里的一个 `PlaceResult`。
+- 尺寸是某个类型的事实时，写成该类型的 `static constexpr`，例如 `Board::kRowCount`；不要再造一个只做 `static_cast<std::size_t>` 的别名常量。
+
 ## 封闭状态与结果
 
 - 状态用连续取值的 `enum class`：`kPending`、`kActive`、`kDone`。

package/skills/developing-cpp/references/types.md

@@ -62,7 +62,7 @@ std::array<TaskState, kItemCount> items_{};
 - 枚举值只在类型作用域内可见：`TaskState::kPending`，不写 `kPending`。
 - 与整数之间不发生隐式转换；需要编号时写 `static_cast<int>(state)`，只用于输出或既有接口。
 - 同类型值可以比较和赋值；不能参与算术。
-- 需要固定布局时写底层类型：`enum class TaskState : std::uint8_t { kPending, kActive, kDone };`
+- 需要固定布局时写底层类型。编号要在头文件里直接读到，就逐个写出来，不靠第一项默认为 0：`enum class TaskState : std::uint8_t { kPending = 0, kActive = 1, kDone = 2 };`
 
 约定：
 
@@ -70,6 +70,8 @@ std::array<TaskState, kItemCount> items_{};
 - 封闭状态码默认写 `: std::uint8_t`；普通枚举用默认底层类型。
 - 枚举值的行尾注释要么全写要么全不写；两种句式与禁止项见 `references/comments.md`「枚举项与 `struct` 短字段：两种句式」。
 - 需要“编号”与“名字”两套表示时，写显式映射函数，例如 `TaskStateToName` / `TaskStateFromName`，不要在枚举和整数之间来回隐式转换。
+- 编号按“失败优先”排：空状态或前置条件失败为 0，业务失败随后，成功放在最后。读取端因此可以先判 0，再决定是否继续。
+- 编号只用于输出和既有接口；要从编号找回名字，仍走显式映射函数，不拿编号做算术。
 
 ## 强类型包装
 
@@ -111,6 +113,8 @@ class TaskBoard {
 
 - 只给“结果携带信息、忽略会出错”的函数：查询型 `const` 成员与返回结果对象的 API。
 - 不给所有非 `void` 函数机械添加；标注的价值来自稀缺。
+- 写法位置：`[[nodiscard]]` 在返回类型前面，然后才是 `static` 或 `constexpr`；参数列表之后才是 `const`、`override`、`noexcept`。
+- 类内 `friend` 不加 `[[nodiscard]]`：Clang 拒绝 `[[nodiscard]] friend`、`friend [[nodiscard]]` 和参数列表后的 `[[nodiscard]]`。不要再猜下一种写法。
 - 有意丢弃时写 `static_cast<void>(result)`，不要为此全局关闭警告。
 - 测试里验证“必须处理结果”时，同时验证忽略能被编译器发现。