# 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需要手动配。# Python McCabe代码复杂度的度量与思考先从一个日常场景说起调试一段别人写的代码看起来不过几十行可读着读着就像走进了一个没有尽头的迷宫if 套着 iffor 循环里还藏着 while 循环各种分支像岔路一样让人晕头转向。这种感觉其实就是代码复杂度太高的体现。Python 里有个叫 McCabe 的工具就是为了应对这种情况而生的。它是什么McCabe 本质上是一个基于圈的复杂度度量工具。这里的“圈复杂度”是一种量化程序分支结构的指标简单来说就是统计代码中独立线性路径的数量。每多一个 if、while、for、except 这类控制流关键字路径就会分叉。McCabe 这个名字来源于 Thomas McCabe他在 1976 年提出了这个概念。实现方式很直接代码就是一张图控制流就是图中的边和节点。圈复杂度 边数 - 节点数 2。拿个函数举例如果没有任何分支复杂度就是 1每多一个 if 就多 1每个循环也多 1包括每个 except 和 case 分支都会增加复杂度。它能做什么最主要的用处是找出代码里那些过于复杂的函数。现实开发中经常遇到这样的情况一个函数有两三百行嵌套了好几层 if-else还有各种循环。这样的代码看上去功能正确可一旦需要修改或者扩展谁都害怕——因为不知道动一处会牵连多少路径。举个例子处理订单状态的函数可能有待支付、已支付、已发货、已签收、已退货等十几个状态每个状态都有不同的操作逻辑还可能叠加各种条件。这样的函数圈复杂度轻松就能到 20 以上。而 McCabe 会直接告诉你这个数字有多高。另一个实际场景是新同事加入项目代码审查时有个客观指标可以用。不是说复杂度高就不能过而是要讨论为什么高怎么拆解。McCabe 提供了一个共同语言避免了“我觉得这个函数太复杂”这种纯主观的说法。怎么使用安装很简单pip install mccabe。然后在代码审查或者 CI 流程中执行python-mmccabe your_module.py--min10这个命令会列出所有圈复杂度超过 10 的函数。min 参数可以自己设项目初期建议用 5 左右成熟项目可以用 10。输出格式大概是your_module.py:15:1: handle_order 12 your_module.py:42:1: validate_user_input 18数字就是圈复杂度。在实际项目中我通常把它集成在 pre-commit hook 里repos:-repo:https://github.com/pycqa/mccaberev:0.7.0hooks:-id:mccabeargs:[--min10,--show-complexity]这样每次提交前都会自动扫描超过阈值的文件直接报错不让提交。最佳实践根据多年用下来的经验有几个值得留意的点。阈值要分语境。业务逻辑复杂的核心模块圈复杂度 15 以内都算合理但如果是工具函数、辅助方法超过 5 就值得拆解。建议团队内部分层设定而非一刀切。不要过度追求低复杂度。曾经见过一个项目为了把圈复杂度降到 2 以下把原本 30 行的函数拆成了 8 个函数每个函数只有 2-3 行然后这 8 个函数之间又互相调用。代码的混乱程度反而更高了因为要跳转 8 个文件才能理解一条业务逻辑。圈复杂度只是个警示信号不是最终目标。拆解复杂函数时有个实用的视角看看哪些条件是互斥的把它们提取成独立的处理函数那些只有 1-2 个条件的分支考虑用字典映射代替 if-else 链。比如处理不同用户角色的权限校验用字典把角色名映射到函数比写一串 if-elif 要清晰得多。和同类技术对比Python 生态中有几个相似的度量工具。radon 是个综合性较强的代码度量库涵盖了圈复杂度、原始指标、Halstead 复杂度等。它的圈复杂度计算和 McCabe 本质相同但 radon 提供了更多维度的分析。实际选择时如果只需要圈复杂度McCabe 更轻量如果需要整体质量评估radon 更合适。pylint 也会报告代码复杂度但它主要做静态分析圈复杂度只是众多检查项之一默认阈值设置得比较宽松。pylint 的复杂度检查更像是附带的赠品而 McCabe 是专业的复杂度分析工具。还有一个有意思的视角有些团队用 flake8 的插件来集成 mccabe因为 flake8 本身是代码风格检查工具加上 mccabe 插件后风格问题和复杂度问题一次扫描完成。这样配置起来更简洁pipinstallflake8 flake8-mccabe然后在 flake8 配置里加上 mccabe 的阈值就行。这种做法比较推荐因为代码审查时通常希望风格和复杂度一起看分开扫描反而多了步骤。说到最后代码复杂度只是众多质量指标中的一个不能替代代码审查和经验判断。但它的价值在于给出一个客观的起点——当圈复杂度超过 10 时至少该停下来想想这个函数的职责是否过于集中了。最近flake8也有个插件叫flake8-docstrings但它本质上是把pydocstyle的检查集成到flake8里。跟interrogate的哲学不同它还是偏重格式而非覆盖率。说到底interrogate解决的不是怎么写好文档的问题而是怎么让大家都记得写文档的问题。它就像代码仓库里站着个尽责的保安没什么创意但让人放心。对于大多数团队来说这恰恰是最需要的。