interrogate 文档字符串覆盖率门禁

文档字符串覆盖率为何需要门禁

在多人协作的 Python 项目中，文档字符串的缺失往往是一个渐进式的问题。新模块上线时大家都记得写文档，但随着迭代推进，新增的函数和类常常忘记补充说明。等到代码审查时才发现，要么靠口头约定，要么靠人工检查，效率极低且难以标准化。interrogate 要解决的就是这个问题——将文档字符串覆盖率变成一个可以量化、可以自动化检查的指标。

核心能力与工作方式

这个技能的核心思路很简单：用 interrogate 对 Python 源码树进行静态扫描，统计每个模块、类、函数是否包含文档字符串，然后计算整体覆盖率。当覆盖率低于你设定的阈值时，命令以非零退出码结束，从而在 CI/CD 流程中触发失败。

关键步骤包括：

• 定义阈值：根据项目阶段设定合理的覆盖率门槛，例如新项目 90%、存量项目逐步提升
• 运行检查：在 CI 流水线中执行 interrogate 扫描整个源码树
• 门禁拦截：覆盖率不达标时阻断合并，确保文档质量不会持续下滑

适用边界与注意点

• 要求 Python 3.8 及以上版本，需在已有 Python 源码树的项目中使用
• 阈值设定需要团队达成共识，过高会导致开发阻塞，过低则形同虚设
• interrogate 只检查文档字符串是否存在，不校验文档内容质量
• 对于大量遗留项目，建议分阶段引入，先从新增代码开始逐步覆盖