python interrogate

# Python Interrogate：一个被低估的代码质量卫士

在Python项目里摸爬滚打这些年，见过太多"纸面文档"——README写得天花乱坠，代码里却连个像样的docstring都没有。这种反差带来的痛苦，估计每个接手过别人代码的人都懂。今天聊聊interrogate，这个专门治"文档懒惰症"的工具。

它到底是个什么玩意儿

Interrogate本质上是个docstring覆盖率检查器。它不像pylint那样管语法错误，也不像mypy那样盯类型注解，它的关注点特别单纯：你的代码里有多少函数、类、模块写了文档字符串。

说得直白点，它就像个文档考勤机。你写了个函数，它就去看看这个函数的docstring是不是空的。每个参数有没有说明，返回值有没有说清楚，异常有没有写明白。它不管你的注释写得对不对、通不通顺，只看你有没有写。

这个工具的bug在于，很多人写docstring完全看心情——高兴了三行，不高兴就pass。interrogate就是要把这种"心情驱动"变成"数据驱动"。

它真能派上用场的地方

最直接的作用当然是当"文档警察"。项目里设置个门槛，比如docstring覆盖率必须达到90%以上，pull request才能过。这招对团队里那些觉得"写完代码就完事了"的同事特别有效。

不过我觉得它最有价值的地方，其实是当一面镜子。跑一遍interrogate，看看哪些函数没有docstring，基本就能判断出哪些代码最需要重构。逻辑复杂的函数不写文档，大概率是写的人自己也理不太清楚。文档少的模块，往往也是代码质量最堪忧的模块——这背后的直觉是：写得清楚的代码，通常也说得清楚。

还有个不太起眼但很实用的场景：新人接手老项目。跑下interrogate，覆盖率低的地方就是需要重点理解的模块，覆盖率高但写得一堆废话的地方……那可能是前一个哥们儿在刷KPI。

上手其实很简单

装它只需要一行：

pipinstallinterrogate

跑一遍你的项目：

interrogate your_project/

出来就是一个清晰表格，告诉你哪些文件达标，哪些欠账太多。有个细节：默认情况下它会跳过测试文件，因为测试里的辅助函数写docstring确实意义不大。

真正有意思的是配置文件。在pyproject.toml里加这么一段：

[tool.interrogate] fail-under = 80 verbose = 2 ignore-init-method = true

fail-under设定的是红线——低于这个百分比，程序返回非零退出码。在CI脚本里直接用这个判断是否通过。ignore-init-method是个有人喜欢有人恨的选项：__init__方法要不要写docstring？我个人的习惯是，如果初始化逻辑不复杂，写个类级别的docstring就够了。

还有个exclude参数可以减少误报。比如项目里有些自动生成的代码，或者第三方的接口封装，没必要强求docstring：

[tool.interrogate] exclude = ["migrations/*", "auto_generated/*"]

几点真有用的经验

第一，别追求100%覆盖率。95%就很好，剩下的5%可能是些极度简单的一行getter、setter，强行写docstring反而显得刻意。关键是把"明显需要解释"的地方都覆盖到。

第二，interrogate要和文档审查配合。它只能告诉你"有没有"，不能告诉你"好不好"。一个人写了"返回结果"三个字，覆盖率算达标了，但跟没写差不多。可以再结合个文档质量检查规则：docstring少于一定字数的，也要标记。

第三，建议在项目初期就引入。等代码堆到几万行再回头补docstring，那感觉就像把散落的乐高重新拼起来——痛苦不说，还容易写错。刚开项目的时候设个80%的门槛，后面的代码自然就不会积累太多"文档债"。

第四，留意它的verbose模式。加-v参数能看到具体的漏网之鱼，加-vv可以列出所有文件和它们的详细得分。调试的时候用-vv找问题模块特别直观，不用手动翻代码。

和其他工具比比看

跟pydocstyle比，interrogate更像个"数字派"。pydocstyle管的是文档字符串的格式规范，比如冒号、缩进、是否用Google风格。interrogate只管盖没盖章。一个管质量，一个管数量，不过我觉得数量是质量的必要前提——docstring都没写，何谈格式对不对。

Sphinx的napoleon扩展能自动把docstring转成漂亮文档，interrogate跟它也不冲突。先用interrogate保证每个接口都有docstring，再用Sphinx生成文档，流程挺顺的。

还有个叫docstr-coverage的，跟interrogate功能几乎一样。它的优势是支持更多自定义规则，比如可以按参数个数来决定是否强制写docstring。但interrogate更轻量，配置更简单，默认行为更合理——比如自动忽略构造函数这种，docstr-coverage需要手动配。

最近flake8也有个插件叫flake8-docstrings，但它本质上是把pydocstyle的检查集成到flake8里。跟interrogate的哲学不同，它还是偏重格式而非覆盖率。

说到底，interrogate解决的不是"怎么写好文档"的问题，而是"怎么让大家都记得写文档"的问题。它就像代码仓库里站着个尽责的保安，没什么创意，但让人放心。对于大多数团队来说，这恰恰是最需要的。