DKChan
f406002766
- git mv 15 件本体；13 个引用文件 34 处路径同步＋熵增闸 DESIGN_SUBDIRS 白名单同批改判 - 白名单漏改时熵增闸当场真红（子目录越界拦截能力实录验证），同步后全绿 - game/tests 三件套注释按用户特别授权批后主区直改（不入本批）；reports/research 暂存档按吸收即死原则不改 - 文档域闸全绿：gdd_lint/doc_link/doc_term/流水线闸/熵增闸
56 lines
3.1 KiB
Markdown
56 lines
3.1 KiB
Markdown
# 代码规范反面案例库（code-conventions 配套）
|
||
|
||
> 本文件是 `code-conventions.md` 各条规则对应的真实反例，说明每条规则针对什么缺陷；规则本体以规约为准，规约与本文冲突时以规约为准。不随规约常驻加载——写码前不必通读，对某条规则的适用有疑义时再查。
|
||
|
||
## 1.1 上帝对象
|
||
|
||
main.gd 曾长到 ~1100 行——棋盘渲染、HUD、结算日志格式化、四种模态覆盖层、调整板、模拟器、关卡流程全部内联；后拆分为 9 个单一职责单元（views/ + hud_presenter），main 回到 ~430 行组合根。
|
||
|
||
## 1.2 裸函数堆
|
||
|
||
供给控制器曾以裸函数伪代码呈现被否；正式实现按私有组合件 RewardSupplyController 封装。
|
||
|
||
## 1.4 ID 前缀命名
|
||
|
||
ID 前缀是跟随 GDD 文档名的事实约定，从未成文；`config_db`/`rng_service` 无前缀与 A/B/C 系列并存——两套命名并行即规范缺失。
|
||
|
||
## 1.4.1 文件头失守
|
||
|
||
main.gd 头注曾累积 42 行——历次提交各自追加「本批做了什么」而全部闸静默放行；删掉叙事后仍剩 31 行，约 2/3 是对 code-conventions §1.3 与架构文档的整段复制、场景结构/生命周期机制描述（对规约与代码零新信息）。
|
||
|
||
## 2.1 信号契约缺失（软锁）
|
||
|
||
封印动作花完末点 AP 后相位翻 Waiting 但不发 round_end，结算点依赖该事件 → 整局软锁；自动玩家不用封印，冒烟路径覆盖不全没抓住。
|
||
|
||
## 2.2 标识符语义错位
|
||
|
||
窗口选择契约 = 窗口条目位置，UI 却传库存数组句柄——未消耗时二者巧合相等；消耗一件后错位 → 选中件不消耗、邻件被误耗。
|
||
|
||
## 2.3 覆盖层不可达
|
||
|
||
数值调整板已实现，但打开时被不透明的开始覆盖层完全遮住 = "点击无反应"。功能存在 ≠ 功能可达。
|
||
|
||
## 2.4 状态字段语义隐式
|
||
|
||
spawn 把 hero 的 max_hp 设为入参 hero_hp——跨战斗携带 HP 时上限被压扁，恢复点/治疗包的满血守卫全部失效。
|
||
|
||
## 5.3 单尺度校准的关卡灾难
|
||
|
||
可选类 25% 格子配比在单战斗尺度校准（击杀需求 18/54），×"库存关内延续"× 5 张板复合后 = 每关 24.8 件、刀总伤 180 > Boss 130 HP——单尺度合理的参数在关卡尺度坐实灾难。
|
||
|
||
## 5.4 拍板范围外自行发挥
|
||
|
||
清图奖励被自行设计成入库刀，用户纠正为"一次性高额伤害不入库"。
|
||
|
||
## 缺陷-规范对照表
|
||
|
||
| 缺陷 | 现象 | 对应规则 |
|
||
|---|---|---|
|
||
| UI 抖动 / "第3轮"消失 | 悬停文案换行推挤侧栏，末行被挤出视口 | 1.1 拆分 + 视图定长槽 |
|
||
| Boss 战 AP 用完不结算（软锁） | 封印耗尽末点 AP 后整局冻结 | 2.1 事件发射完整性 |
|
||
| 道具使用后不消失 | 选用件留存、邻件被误耗 | 2.2 标识符语义单一 |
|
||
| 调整板点击无反应 | 面板已实现但被开始层遮挡 | 2.3 层级规则 + test-conventions §2 |
|
||
| 上帝对象 | main.gd ~1100 行 | 1.1–1.3 |
|
||
| ID 前缀命名 | 两套命名并存 | 1.4–1.5 |
|
||
| 可选类每关 24.8 件 | 速杀退化、囤刀秒 Boss | 5.3 跨尺度推演 |
|