# 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 truefail-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解决的不是怎么写好文档的问题而是怎么让大家都记得写文档的问题。它就像代码仓库里站着个尽责的保安没什么创意但让人放心。对于大多数团队来说这恰恰是最需要的。