python mccabe

# 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需要手动配。

# Python McCabe：代码复杂度的度量与思考

先从一个日常场景说起：调试一段别人写的代码，看起来不过几十行，可读着读着就像走进了一个没有尽头的迷宫，if 套着 if，for 循环里还藏着 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.0'hooks:-id:mccabeargs:[--min=10,--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解决的不是"怎么写好文档"的问题，而是"怎么让大家都记得写文档"的问题。它就像代码仓库里站着个尽责的保安，没什么创意，但让人放心。对于大多数团队来说，这恰恰是最需要的。