# 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)