Files
dacli/docs/decisions/0009-code-comment-hygiene.md
sushub f403a7e80e import: ssw/dacli@eea0ebc (2026-08-12) 起点版本
本仓 2026-08-12 从 ssw main (192.168.1.18:13300/ssw/ssw-mvp) 的
dacli/ subpath 抽取,作为独立仓托管到 gitea:3000/ssw/dacli.git。

- 工作树为 ssw main dacli subpath 最新版 (110 commit, 08-12)
- 历史未带 ssw main 整体历史(避免大仓污染)
- 此为新仓基线 commit,未来以本仓历史为主
2026-08-12 15:58:06 +08:00

2.2 KiB

0009-code-comment-hygiene

日期: 2026-07-17 状态: Accepted 作者: claude-code

Context

dacli 源码随 drift 轮次迭代 (R1-R17) 积累了大量注释, 包含 BS-编号、jxcj 实战细节、v0.x 版本标记、反模式编号等内部信息。这些注释在开发期有价值 (追溯设计理由), 但在稳定期:

  1. 增加代码噪音, 降低可读性
  2. 部分注释随代码变更而过时 (漂移)
  3. 设计理由本应由 ADR/doc 承载, 不应散落在代码中

CLAUDE.md 明确要求 "准确和必要原则", 但未定义注释的保留/删除标准。

Decision

代码注释采用 "当前代码必需的" 标准, 分为 4 类可保留:

  1. 设计意图: 解释为什么这样做 (不是做了什么) — e.g. "// BS-18 fallback: modelId may use enCode instead of formId"
  2. 约束说明: 标注外部依赖的限制 — e.g. "// JNPF web 端 PUT 不调 addTableFields, 物理表不同步"
  3. web 源码路径: 标注镜像的 web 源码位置 — e.g. "// mirrors: web/.../buildFormData.ts:142"
  4. 反模式警告: 标注易踩的坑 — e.g. "// ANTI-PATTERN: 不要直接用 matched.enCode 当 modelId"

设计理由类注释 (为什么当初这样选) 归位到 dacli/docs/decisions/ ADR, 不留在代码中。代码只保留 "当前维护者需要知道的"。

Alternatives Considered

  1. 保留所有注释 + 定期清理: 不自动化, 会漂移; 清理时难以判断哪些该留。
  2. 禁止所有注释: 过于极端, 设计意图/约束说明对维护者有价值。
  3. 注释前加标签归类: [DESIGN] / [CONSTRAINT] / [MIRROR] / [WARNING]。增加格式负担, 不如靠位置 (ADR vs 代码) 区分。

Consequences

正面

  • 代码更简洁, 维护者聚焦于当前逻辑
  • 设计理由集中管理 (decisions/), 便于查阅和更新
  • 减少注释漂移 (过时注释误导维护者)

负面

  • 需要纪律: 每次改设计时同步更新 ADR
  • 新人看代码时可能不理解上下文 (需额外查 ADR)
  • 重构时 ADR 和代码的对应关系可能断裂

Cross-refs

  • CLAUDE.md § "准确和必要原则"
  • template.md: ADR 标准结构
  • This ADR itself is the first application of the rule (design rationale for comment hygiene lives here, not in source code)