# 1. "注释撒谎"问题中注释与代码不同步时如何通过 CI 检测（markdownlint、Vale、textlint 校验文档与链接，扫描失效引用与过时示例）？ A 让开发者自觉保证注释与代码同步 B 注释只写"high-level"不写细节 C 删除所有注释，从根源避免撒谎 D 在 CI 中接入 markdownlint/Vale/textlint 校验文档，用 link-check 扫描失效引用，用 doctest 校验代码示例可运行 ✓ 正确答案
# 2. Javadoc / GoDoc / docstring 中"@throws"与"@param"的契约化使用中当异常类型在多个子类型之间动态分发时文档如何既不撒谎又不冗余 A 逐个列出所有子类异常 B 只写超类 RuntimeException，不写细节 C 描述"何时抛"的触发条件与可处理契约，具体子类分发交给错误码文档，避免冗余与撒谎 ✓ 正确答案 D 不写 @throws，让调用方自行尝试
# 3. KDoc / DocC（Swift） / TSDoc / Rustdoc 的交叉链接与代码示例可执行化（runnable doctest）的 CI 集成策略 A 示例随意写，无需运行 B 文档示例与真实代码允许不同步 C 交叉链接只用于人读，不校验 D 示例优先引用真实源码（snippet），并让示例编译运行纳入 CI；交叉链接用构建期断链校验 ✓ 正确答案
# 4. OpenAPI / GraphQL 描述与代码注解（@Schema(description=...)）双向同步工具链 A 代码与文档各写一份，允许不一致 B 只维护文档，不写注解 C 确立单一事实来源（code-first 用注解生成文档，或 design-first 用契约生成代码），并用 CI diff 校验防止双向漂移 ✓ 正确答案 D 注解只影响序列化，不影响文档
# 5. TODO/FIXME 等临时标记注释的生命周期治理中如何用门禁、超期提醒与 issue 关联避免"临时注释"沉淀为永久技术债？ A 不再使用 TODO 注释 B TODO 越多越好，代表在改进 C TODO 关联 issue、设置期限，用 CI 门禁统计与超期提醒跟踪，定期清理避免沉淀 ✓ 正确答案 D TODO 无需管理，自然消失
# 6. 公共 API 的文档覆盖率门禁中如何统计缺失 Javadoc/TSDoc 的公开符号并纳入 CI，防止文档欠账无声累积？ A 用 lint/工具统计公开符号缺失文档，CI 在 PR 阶段拦截新增欠账，存量用豁免清单渐进收敛 ✓ 正确答案 B 存量代码一次性全部补文档再上线 C 只统计不拦阻，文档缺失不影响合并 D 文档覆盖率门禁无价值
# 7. 架构决策记录（ADR）与代码注释的边界中哪些"为什么"应放在 ADR、哪些应留在行内注释；变更时如何避免漂移 A 所有"为什么"都放 ADR B 不写注释，只写 ADR C 所有"为什么"都放行内注释 D 架构级决策的"为什么"放 ADR，局部实现级的"为什么"放行内注释，用链接关联避免重复与漂移 ✓ 正确答案
# 8. 注释中包含敏感信息（内部地址、密钥提示、员工姓名）的发现与自动清除工具（gitleaks、talisman、trufflehog） A 用 gitleaks/talisman/trufflehog 在提交与 CI 阶段拦截新泄露，trufflehog 排查历史并用 git filter-repo 清除，同时规范禁止密钥入注释 ✓ 正确答案 B 无需处理，注释不敏感 C 只用人工审查 D 密钥注释可以保留，因为仓库是私有的
# 9. 示例代码（example、sample）随版本漂移的问题中如何在 CI 中运行/编译所有文档中的代码示例（doctest、mdbook、Swagger Editor） A 用 doctest/mdbook test 编译运行示例、Swagger Editor 校验 API 示例，并优先引用真实源码（snippet），纳入 CI 兜底 ✓ 正确答案 B 示例不运行，读者自行判断 C 示例与实现分离，允许漂移 D 只写示例不写实现
# 10. CHANGELOG 维护（Keep a Changelog）与语义化发布（SemVer）的联动中 Added/Changed/Deprecated/Removed/Security 分类如何映射到 minor/major A 所有变更都 bump major B Removed 对应 major，兼容新增对应 minor，修复对应 patch，Deprecated 预告移除；分类决定版本跳动 ✓ 正确答案 C 版本号与 CHANGELOG 无关 D 只需维护 CHANGELOG，不 bump 版本
# 11. README 的必备要素（快速开始、架构图、贡献指南、许可证）及其在 CI 中的可读性检查（死链检测、代码示例可运行） A README 只写简介即可 B 必备快速开始、架构、贡献指南、许可证等，CI 用死链检测与示例执行保证可读且不失效 ✓ 正确答案 C README 无需在 CI 中检查 D 死链不影响 README 质量
# 12. CHANGELOG 与 Conventional Commits 的自动生成（standard-version、release-please）与人工润色的边界 A 全部人工手写 CHANGELOG B 提交信息无需规范，工具也能生成 C 完全自动生成，无需人工 D 工具从 Conventional Commits 自动生成条目与版本，人工补充"为什么"与迁移指引，二者分工 ✓ 正确答案
# 13. 注释的黄金法则中解释"为什么"而非"是什么"，避免过时注释？ A 注释应解释"是什么"，代码无需阅读 B 注释解释"为什么"（权衡、约束、坑），"是什么"由命名与结构表达，避免过时注释 ✓ 正确答案 C 注释越多越好 D "为什么"注释必然过时，应删除
# 14. 文档与代码同步中文档即代码（docs-as-code）的实践？ A 文档与代码分离维护，互不影响 B 文档与代码同仓库同评审，生成类文档由代码驱动，叙述类文档引用真实代码并纳入 CI，保证同步 ✓ 正确答案 C 文档用二进制格式，不参与 diff D 文档只在发布时补写
# 15. 多语言团队的注释语言选择中注释用英文还是母语，对跨国协作、拼写检查与工具链的影响如何统一？ A 注释随意用语言，个人自由 B 标识符可用中文 C 必须用母语 D 统一注释语言（跨国协作推荐英文），标识符用英文，用 CI 拼写检查强制，保证全仓一致 ✓ 正确答案
# 16. "代码即文档"理念下何时仍需要写注释；常见的过度注释反例 A 任何代码都加注释 B 写"为什么"、边界与非显然逻辑的注释；"是什么"由代码自明，避免重复代码的过度注释 ✓ 正确答案 C 完全不写注释 D 注释越多越好，即使重复代码
# 17. 方法级注释的 4 段式结构（@param、@return、@throws、@since）的一致性检查 A 注释随意，无需与签名一致 B @since 可省略，不影响契约 C 只写 @param 即可 D @param/@return/@throws 与签名一一对应，用 doclint/checkstyle 自动校验缺失或多余 ✓ 正确答案
# 18. 注释的坏味道中冗余注释、被注释掉的代码与误导性注释？ A 冗余注释、被注释掉的代码、误导性注释都应保留以作参考 B 误导注释比无注释更安全 C 被注释掉的代码是良好实践 D 冗余注释应删除，被注释掉的代码应删除（用 Git 找回），误导注释应更正或删除 ✓ 正确答案
# 19. API 文档的规范中 Javadoc/TSDoc 的标签与示例？ A 公共符号可不写文档 B 示例无需与签名一致 C 只写 @deprecated 就够 D 用 @param/@returns/@throws/@deprecated/@example 等标签表达契约，配合覆盖率门禁与一致性校验，示例可运行 ✓ 正确答案
# 20. commit message 与行内注释的信息分工中二者不能互相替代，各自的职责边界是什么？ A 二者可互相替代，写一个即可 B 只需 commit message C commit message 记录变更历史（变更 why），行内注释记录现状约束（状态 why），面向不同场景，不可互相替代 ✓ 正确答案 D 只需行内注释
