本仓 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,未来以本仓历史为主
2.2 KiB
2.2 KiB
0009-code-comment-hygiene
日期: 2026-07-17 状态: Accepted 作者: claude-code
Context
dacli 源码随 drift 轮次迭代 (R1-R17) 积累了大量注释, 包含 BS-编号、jxcj 实战细节、v0.x 版本标记、反模式编号等内部信息。这些注释在开发期有价值 (追溯设计理由), 但在稳定期:
- 增加代码噪音, 降低可读性
- 部分注释随代码变更而过时 (漂移)
- 设计理由本应由 ADR/doc 承载, 不应散落在代码中
CLAUDE.md 明确要求 "准确和必要原则", 但未定义注释的保留/删除标准。
Decision
代码注释采用 "当前代码必需的" 标准, 分为 4 类可保留:
- 设计意图: 解释为什么这样做 (不是做了什么) — e.g. "// BS-18 fallback: modelId may use enCode instead of formId"
- 约束说明: 标注外部依赖的限制 — e.g. "// JNPF web 端 PUT 不调 addTableFields, 物理表不同步"
- web 源码路径: 标注镜像的 web 源码位置 — e.g. "// mirrors: web/.../buildFormData.ts:142"
- 反模式警告: 标注易踩的坑 — e.g. "// ANTI-PATTERN: 不要直接用 matched.enCode 当 modelId"
设计理由类注释 (为什么当初这样选) 归位到 dacli/docs/decisions/ ADR, 不留在代码中。代码只保留 "当前维护者需要知道的"。
Alternatives Considered
- 保留所有注释 + 定期清理: 不自动化, 会漂移; 清理时难以判断哪些该留。
- 禁止所有注释: 过于极端, 设计意图/约束说明对维护者有价值。
- 注释前加标签归类:
[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)