docs(编号): 语义标识定为唯一默认形态,并把「还有多少号可清」写成存量清点与三批计划
用户原话定了调子:**不要用字母加数字的编号,简直太难以理解了,语义标识是最好的**。本文此前的立论是 「默认不用编号、例外只有 8 族」,方向对但不够硬,而且**有一处真缺陷**——§4.1 那张表自称「穷举」,实测 却发现有四类**仍在用**的族不在表里:登记簿旧号残留(4 站点)、阶段号(1)、台架阶段裸形(19)、网络设计 条目号(38)。自称穷举而实际漏登,比没有表更坏:下一个人会拿它当「这些都可以用」的依据。 本笔四件事: ① 定调改硬:语义标识是唯一默认,编号是**例外**,例外只留「有脚本按字面量匹配」的那几种; ② §4.1 拆两栏:『允许继续发号』8 族(逐条给脚本依赖理由)与『已停发、存量待清』4 族——后者登记未删只是 为了让历史行不报「未登记前缀」,**不得再新增引用**; ③ 新增 §9 存量清点,数字全部用门禁自己的接口实测、非估算:**26 个族仍有引用、565 个不同字面量、 1,108 个引用站点**;其中 TC 族 561 站点 / 472 字面量 / 77 文件、保护功能号 184 / 28 / 58、 TRAP 族 134 / 25 / 51、网络设计条目号 38 / 12 / 20、代码规范条款号 35 / 20 / 13、台架阶段裸形 19 / 4 / 12、登记簿旧号 4 / 3 / 3、阶段号 1 / 1 / 1; ④ 三批计划按「值不值得动门禁」排序:批次一 62 站点不碰门禁即可清(那四族没有任何脚本按字面量匹配、 纯人读);批次二 184 站点把保护功能号改成功能名(「过流Ⅰ段」这类,须按功能逐个改、不能全局替换); 批次三 TC 族 561 站点**不是改文本而是换追溯机制**(用例名即标识 + 断言标签改短语),代价是追溯门禁 重写并重打基线、当天在飞分支全要跟改 ⇒ 建议单开一张卡,等你裁定再动。 §8.1 基线按今日复测重打:784 文件 / **8,787 字面量**(两批清理前 10,956 → 8,230,此后新代码新文档回涨), 比例 86.79%(基线 86.0%)。自查:doc-links --all exit 0(195 文档)、本篇 --sections-strict 通过、 check_ids --strict exit 0、不可判定绝对数 1,161 / 上限 1,166(本笔新增的是可判定引用); 文件 noBOM / LF / U+FFFD=0 / 结尾换行齐。
This commit is contained in:
+63
-13
@@ -1,11 +1,13 @@
|
||||
# 编号规范:默认**不**用编号
|
||||
|
||||
> **一句话:能把事实写清楚,就别发号。** 全项目允许使用「字母+数字」编号的族只有 **8 个**(§4.1),
|
||||
> 它们的共同点只有一个——**有脚本按字面量匹配它**。除此之外,一律写语义短语(§3.3)。
|
||||
> **一句话:语义标识是唯一默认形态,编号是例外。** 例外只留给**有脚本按字面量匹配**的那几种
|
||||
> (§4.1 的「允许继续发号」一栏);同一张表里还有一栏是**已停发、存量待清**的族(§9.1 给清点与批次)。
|
||||
> 除此之外一律写语义短语(§3.3)。
|
||||
>
|
||||
> 这条不是洁癖:规划 / 待办 / 审计 / 差距 / 阶段这些给人看的东西,历史上全发过号,也全都变成了
|
||||
> 没人认得的代号。2026-10-26 一天清了两批 + 本文瘦身,编号字面量 **10,956 → 8,230 处**(§8.1),清掉的号里
|
||||
> 绝大多数从来没被任何脚本读过一次。沿革与教训留在 §8.3 与 git log,正文不复述。
|
||||
> 这条不是洁癖,是用户 2026-10-27 的明确要求:**「不要用字母加数字的编号,简直太难以理解了,语义标识是最好的」**。
|
||||
> 依据也很硬:规划 / 待办 / 审计 / 差距 / 阶段这些给人看的东西,历史上全发过号,也全都变成了没人认得的代号。
|
||||
> 2026-10-26 起两批清理把编号字面量从 **10,956 压到 8,230 处**,2026-10-27 复测为 **8,783 处**(§8.1 有口径说明);
|
||||
> 而清掉的号里绝大多数从来没被任何脚本读过一次。沿革与教训留在 §8.3 与 git log,正文不复述。
|
||||
>
|
||||
> **机器面才是事实源**:族注册表 `scripts/id_registry.json`、旧号别名 `scripts/id_aliases.json`、
|
||||
> 门禁 `scripts/check_ids.py`(八项校验,详解 `docs/门禁说明/id-check.md`)。本文与机器面冲突时
|
||||
@@ -55,7 +57,7 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|---|---|---|
|
||||
| ① 最好 | **语义短语** | 规划 / 待办 / 缺陷 / 风险 / 决策 / 差距 / 文档内步骤与阶段——**默认形态** |
|
||||
| ② 其次 | **文档名 + 章节号** | 指某篇文档的某节(`docs/网络/网络自愈架构设计.md` §4.10,紧邻写法) |
|
||||
| ③ 最后 | **编号** | 只有 §4.1 那 8 个族,且必须能反查到定义 |
|
||||
| ③ 最后 | **编号** | 只有 §4.1「允许继续发号」那一栏,且必须能反查到定义 |
|
||||
|
||||
### 3.1 判定口诀
|
||||
**机器读 → 发号;人读 → 写短语。** 拿不准就写短语:短语看不懂还能靠上下文猜,号看不懂只能去查表。
|
||||
@@ -80,7 +82,7 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
### 4.1 允许用号的族(**穷举**——这张表以外一律不许发号)
|
||||
|
||||
| 族 | 形态 | 属主登记处(定义在哪查) | 为什么必须是号 |
|
||||
**允许继续发号**(有脚本按字面量匹配,现状实测 2026-10-27 见 §9.1):
|
||||
|---|---|---|---|
|
||||
| `TC-*` | `TC-<模块码>-<序号>` | `docs/测试说明/*_Test_Guide.md`、`test/host/<模块>/*`(代码即登记处) | 用例↔断言双向追溯,要进 C 断言标签 |
|
||||
| `TRAP-*` | `TRAP-<域>-<nn>` | `docs/问题记录/*_Trap_Records.md` | 踩坑证词的永久锚点,代码注释反查 |
|
||||
@@ -91,6 +93,15 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
| `MENU-STATE-<nn>` | UI 状态机键 | `simulator/tests/check_menu_rows.py` | 像素回归脚本按它取状态行 |
|
||||
| `P-<n>` | **本文的设计原则** | 本文 §2 | 就是本文自己的条目 |
|
||||
|
||||
**已停发、存量待清**(登记未删只是为了让历史行不报「未登记前缀」,**不得再新增引用**;清点见 §9.1):
|
||||
|
||||
| 族 | 形态 | 存量 | 为什么该清 |
|
||||
|---|---|---|---|
|
||||
| `N-*` | 登记簿 `N-<nn>` | 4 处 / 3 个字面量 | 登记簿已于 2026-10-26 全面改语义短语,残留的是漏网的旧引用 |
|
||||
| `TM-*` | 阶段/里程碑 `TM-<code>-<nn>` | 1 处 | 阶段号本就属 §3.3 明令不许写号的那类 |
|
||||
| `T-TEST` | 台架阶段 **裸形** `T0~T3` | 19 处 / 4 个 | 裸形最危险(同字母多义),且改「台架阶段一」即可 |
|
||||
| `F-*` | 网络设计条目 `F-<MOD>-<nn>` | 38 处 / 12 个 | 代码注释按号回指设计条目,但没有任何脚本匹配它 |
|
||||
|
||||
- **新增族的唯一正当条件**:有脚本要按字面量匹配它。顺序固定:先改 `id_registry.json`(含属主登记处)
|
||||
→ 再写属主文档 → 最后才允许在别处引用。反过来做必然造出悬空号。
|
||||
- 模块码是既定缩写,事实源 = registry 的族 pattern 与属主文档标题行,**别自创**(§6)。
|
||||
@@ -181,9 +192,9 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
| 项 | 数值 |
|
||||
|---|---|
|
||||
| 扫描文件 / 编号字面量 | 754 个 / **8,230 处**(两批清理前 10,956;本规范自己瘦身去掉 160 处 → 8,343,编号迁移批次再降到 8,230) |
|
||||
| 扫描文件 / 编号字面量 | 784 个 / **8,783 处**(2026-10-27 复测;两批清理前 10,956 → 8,230,此后新代码与新文档回涨 553 处,其中测试用例族占大头,见 §9.1) |
|
||||
| **护栏 1**:可判定比例下限 `decidable_ratio_baseline` | **86.0%**(实测 86.01%;容差 0.1pp,只许涨) |
|
||||
| **护栏 2**:不可判定引用绝对数上限 `undecidable_total_ceiling` | **1,166 处**,只减不增(实跑 1,151 处) |
|
||||
| **护栏 2**:不可判定引用绝对数上限 `undecidable_total_ceiling` | **1,166 处**,只减不增(2026-10-27 实跑 **1,161** 处,余量 5;构成拆解见 `docs/门禁说明/id-check.md` §7.7) |
|
||||
| 校验 1/2/3/4/5/6 错误级 | **0**;债务台账 0 条指纹 → `--strict` 实为**全量拦截** |
|
||||
| 告警 | 悬空 2(`App/algo/freq.c` 的正序 / 负序记号,属 §4.4 误判面)+ 孤儿 50(陷阱条目这类本就允许无人引用) |
|
||||
|
||||
@@ -207,14 +218,52 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
---
|
||||
|
||||
## 9. 还剩什么(以及别再做什么)
|
||||
剩下能被机器读到的号就是 §4.1 那 8 族。除此之外,**"编号说明"这件事本身应该继续变薄**:每多一个族,
|
||||
就多一处需要有人记得它的地方;每多发一个号,就多一个将来没人敢删的字符串。要新增族之前,请把这张
|
||||
只有 8 行的表当作反对你的第一手证据。
|
||||
## 9. 还剩什么:存量清点与批次(2026-10-27 实测)
|
||||
|
||||
先回答「还有多少号可以清」。下面是**用门禁自己的接口跑出来的**存量(`check_ids.py` 的 Checker,按族统计
|
||||
「活引用站点 / 不同字面量 / 涉及文件数」;只统计非冻结族、且排除属主登记处的定义位):
|
||||
|
||||
| 族 | 引用站点 | 字面量 | 文件 | 集中处 | 处置 |
|
||||
|---|---:|---:|---:|---|---|
|
||||
| `TC-*`(含各模块子族) | **561** | 472 | 77 | 测试用例与断言标签、`test/host/**` | **需要先裁定**(见下) |
|
||||
| `L-PROT`(保护功能号) | **184** | 28 | 58 | 保护规划与各模块说明 | 批次二:转语义 |
|
||||
| `TRAP-*` | **134** | 25 | 51 | 踩坑记录与驱动注释 | 保留(可检索锚点,用户已裁定) |
|
||||
| `F-*`(网络设计条目) | **38** | 12 | 20 | `ch395f.h`、`net_events.c` | 批次一:转语义 |
|
||||
| `CODE-RULE-*` | **35** | 20 | 13 | 代码规范门禁 | 保留(门禁按号报错) |
|
||||
| `MENU-STATE-*` | 少量 | — | — | 像素回归脚本 | 保留(脚本按它取状态行) |
|
||||
| `T-TEST`(台架阶段裸形) | **19** | 4 | 12 | 串口/台架脚本与测试流程 | 批次一:转语义 |
|
||||
| `N-*`(登记簿旧号残留) | **4** | 3 | 3 | 规范自身与两处脚本注释 | 批次一:清 |
|
||||
| `TM-*` | **1** | 1 | 1 | 规范自身 | 批次一:清 |
|
||||
|
||||
合计:**26 个族仍有引用、565 个不同字面量、1,108 个引用站点**(其余 73 个登记族已零引用或冻结)。
|
||||
|
||||
### 9.1 三批计划(按「值不值得动门禁」排序)
|
||||
|
||||
**批次一 · 现在就能清(约 62 个站点 / 20 个字面量,不碰任何门禁)**:`N-*`、`TM-*`、`T-TEST`、`F-*`。
|
||||
这四族**没有任何脚本按字面量匹配**,纯人读,正是「语义标识最好」的适用面;`T-TEST` 还是裸形(`T0~T3`),
|
||||
最容易与别的字母撞义。改法:号 → 短语(「台架阶段一」「网络自愈:监听生命周期」),残留引用同步清,
|
||||
别名表标 `void`,台账 `--prune-backlog`。
|
||||
|
||||
**批次二 · 文档为主、量大(约 184 个站点 / 28 个字面量)**:`L-PROT` 保护功能号。它**曾有**明确价值
|
||||
(功能复现规划逐条对齐),但用户已裁定字母号难认 ⇒ 改成功能名本身(「过流Ⅰ段」「零序过流」),
|
||||
规划表首格写功能名、不再配号。要点:必须**按功能逐个改**,不能全局替换(同一号在不同文档指同一功能,
|
||||
但句子结构不同);改完用追溯器复核代码侧没有残留号引用。
|
||||
|
||||
**批次三 · 需要你裁定:`TC-*`(561 个站点 / 472 个字面量 / 77 个文件)**。这是唯一**代码里也大量存在**的族
|
||||
(C 断言标签 + 测试函数名 + 文档用例表),并且 `check_test_traceability.py` 正是靠它做「代码↔文档」双向核对。
|
||||
清它的代价不是改文本,而是**换掉追溯机制**:候选方案是「用例名即标识」(`test_xxx_yyy()` 名字 ↔ 文档表格行名,
|
||||
脚本按名字比对),并把断言标签改成短语。**收益**:全仓字母号一次减掉一半以上;**代价**:追溯门禁要重写并
|
||||
重打基线,且当天所有在飞分支都要跟着改。⇒ 我建议**单独开一张卡**做,不与其他批次混;我这一轮只把批次一的
|
||||
范围与做法写清(§9.2),批次二排在其后,批次三等你一句话。
|
||||
|
||||
### 9.2 别再做什么
|
||||
「编号说明」这件事本身应该继续变薄:每多一个族,就多一处需要有人记得它的地方;每多发一个号,就多一个
|
||||
将来没人敢删的字符串。要新增族之前,请把 §4.1 的「允许继续发号」那 8 行当作反对你的第一手证据。
|
||||
|
||||
## 10. 速查
|
||||
- 看到一个不认识的号 → 先查 `id_aliases.json` 与属主登记表;查不到就**删号留事实**,不要补定义。
|
||||
- 想给待办 / 缺陷 / 差距 / 风险发号 → 不许,写短语(§3.3)。
|
||||
- 想知道「还有多少号可清」→ 看 §9 的存量表与三批计划。
|
||||
- 想给文档内步骤或测试阶段发号 → 不许,写「步骤 3」「阶段 7」(§3.3)。
|
||||
- 想新增前缀族 → 先回答"哪个脚本要按字面量匹配它"(§4.1);答不出就别建。
|
||||
- 要改号 → `scripts/rename_ids.py` + §7.3 五步。
|
||||
@@ -226,4 +275,5 @@ P-6 号必须能反查到定义(属主登记处得存在)· P-7 编号不语
|
||||
|
||||
| 日期 | 变更 | 说明 |
|
||||
|---|---|---|
|
||||
| 2026-10-27 | **语义标识定为唯一默认形态;编号收窄为「机器按字面量匹配」的例外,并首次给出现量清点与三批计划** | 用户原话:「不要用字母加数字的编号,简直太难以理解了,语义标识是最好的」。本笔:① 标题下的一句话从「允许用号的族只有 8 个」改成「语义标识是唯一默认、编号是例外」,并把 §4.1 拆成『允许继续发号』8 族与『已停发、存量待清』4 族(`N-*` / `TM-*` / 台架阶段裸形 / `F-*`)——原表自称穷举,实际漏登记了这三类在用族,属真缺陷。② 新增 §9 存量清点(用门禁自身接口实测:26 族仍有引用、565 个字面量、1,108 个引用站点)与三批计划:批次一 62 站点不碰门禁即可清、批次二保护功能号 184 站点转功能名、批次三 `TC-*` 561 站点需先换追溯机制(等用户裁定)。③ §8.1 基线按 2026-10-27 复测重打:784 文件 / 8,783 字面量、护栏 2 实跑 1,161 / 上限 1,166。 |
|
||||
| 2026-10-26 | **编号治理收口:清死号 → 停发活号 → 本文重写为短版(用户三次裁定)** | 全仓字母+数字编号 10,956 → 8,230 处。① **清死号**:属主登记处已删或从未启用的号一律就地删号留事实、禁补号(文本实删约 1,557 处)。② **停发活号**:登记簿 `N-x`/`S-x`/`T-x`、专项 `A-x`、已删报告的 UI 簇 `U1~U5` 共 20 个号转成语义短语(约 418 处)——登记簿表首格就是短语,旧号进 `scripts/id_aliases.json` 标 `retired-to-phrase`;已销项的死号**故意不进别名表**,让门禁继续咬残留引用。③ **本文瘦身**:619 行 → 229 行,删掉八原则长表、迁移映射表、模块码表与门禁细节(那些各有事实源:registry / 别名表 / `docs/门禁说明/id-check.md`),改成「先问三句再决定要不要发号」+ §4.1 允许用号的族**穷举 = 8 个**。④ **门禁配套**:`check_ids.py` 加变更记录行豁免与第二根护栏 `undecidable_total_ceiling`(比值会被清号动作稀释,绝对数不会),债务台账还清到 0 条 → `--strict` 实为全量拦截,比例基线重打为 86.0%。**本表按用户 2026-10-26 的明确指示只保留最近一条**,更早沿革看 `git log` 与 `docs/门禁说明/id-check.md` §7.5(含其后的方案 B 一节);这是**本文档的例外**,不改变 §5.5对其他文档「冻结历史不回改」的约束。 |
|
||||
|
||||
Reference in New Issue
Block a user