python darglint

Python里有个库叫darglint，名字听起来像某种奇幻生物，实际是个文档参数校验工具。这东西不太起眼，但用好了能省掉不少调试时的头痛。

它是什么

简单说，darglint是个静态分析工具。专门检查函数、方法、类的文档字符串（也就是docstring）里的参数描述，和实际代码里的参数签名是否匹配。比如你写了个函数，定义三个参数，但文档里只记录了两个，或者写了个不存在的参数，darglint会直接指出来。它像给你文档做对齐手术的医生，保证代码的“说明”和“动作”保持一致。

在Python这样的动态语言里，函数签名和文档脱节是家常便饭。很多时候，人改代码时只更新了函数逻辑，忘了改docstring，结果读文档的人拿着过时的说明去用，踩坑。darglint就是解决这种“文档撒谎”的问题。

它能做什么

核心是四类检查：参数是否存在、参数类型是否匹配、返回值是否说明、异常是否记录。实际上它能做的更细一些。

比如参数检查。假设函数签名有def connect(host, port, timeout=30)，但docstring只写了Args: host (str): 主机地址，darglint会报“port和timeout没在文档里”。反过来，docstring里写了username这个参数但代码里没有，它也会报“文档里多了个参数”。

还有返回值。如果函数有返回值但docstring里没写Returns，或者写了但函数实际上返回None，都能检测。异常也是。如果函数里raise了一个ValueError但docstring的Raises里没提，也会被揪出来。

它甚至能理解一些复杂的文档格式，比如Google风格、NumPy风格、Sphinx风格。这点挺实用，不同团队用的风格差别大，darglint能适配。

怎么使用

安装很简单，pip install darglint。安装后，可以直接在命令行用。比如darglint my_module.py，它会扫描整个文件，输出所有发现的问题。

如果想只检查某个函数，可以用darglint --path my_module.py:my_function。扫描结果默认会打印到终端，每行一个错误，说明很具体，比如“参数x未在docstring中列出”。

当然，实际项目中不会每次都手动跑。更常见的是集成到CI流水线里。比如在GitHub Actions或者Jenkins里加一步pip install darglint && darglint src/，这样每次提交代码，自动检查文档一致性。

darglint还可以和flake8配合使用。因为darglint本身也是一个flake8插件，如果你把flake8-darglint这个包装上，在运行flake8时就会自动捎带darglint的检查。好处是统一了代码风格和文档检查的流程。

在编辑器里集成也行。比如VS Code里配置一个task，每次保存文件时自动运行darglint。这种设置虽然小，但长期用下来能避免很多遗漏。

最佳实践

第一点，把darglint的检查纳入代码审查的门槛。不是建议，是必须。如果你团队代码里有几十个函数没写文档，先加个最低要求：所有新函数必须通过darglint检查。旧代码可以慢慢修，但不能让代码库的文档越来越差。

第二点，选择一种docstring风格，并在项目里统一。我的建议是Google风格。它写起来自然，不会把参数说明塞进一大段文本里。darglint对Google风格的支持也最成熟。

第三点，设置darglint的严格级别。darglint默认是“部分严格”，也就是允许缺失某些信息，比如返回值没写但函数有返回，它只报一个警告。想严格点可以设成--level=3，这就变成所有检查必须通过才不报错。不过我建议生产环境项目中用--level=2，它会强制写返回值但允许有些异常描述缺失，折中处理。

第四点，注意darglint和类型注解的关系。如果你的函数用了类型注解，比如def connect(host: str, port: int) -> bool:，darglint不会自动把类型从注解复制到文档里，它只检查参数名和返回值的存在性。这意味着你仍然需要在docstring里写类型，但这样会重复。一个替代思路是干脆不在docstring里写类型，只在注解里写，然后darglint只检查参数名。可以用--no-type-check选项关掉类型检查。

第五点，小心处理私有函数和公共函数的区别。对于内部使用的私有函数（以下划线开头），可以放宽要求，因为团队内部可能不需要那么正式的文档。而公共API必须严格检查。可以通过在pyproject.toml里配置忽略某些模式的正则实现。

和同类技术对比

Python里类似的工具不多，主要竞争对手是pydocstyle和flake8-docstrings。

pydocstyle专注的是文档字符串的格式和规范的完整性，比如有没有写Returns、Args这些段落，但不会检查参数名和代码是否对应。比如pydocstyle能发现你漏写了Args段落，但如果你写了的参数名和函数签名不一致，它查不出来。darglint正好补这个缺口。

另一个是flake8-docstrings，它本质上是pydocstyle的flake8插件。作用范围和pydocstyle一样，都是格式检查。

从覆盖度来看，pydocstyle更像是编辑排版，darglint更像是逻辑校对。两者搭配使用，效果最好。我通常的做法是：先用pydocstyle保证docstring结构正确，再用darglint保证内容和代码同步。

还有一些小众工具，比如docstr-coverage，它只检查某个函数有没有docstring，不深入内容。darglint比它深得多。

所以darglint的优势在于“语义检查”，而不是格式。这恰恰是很多文档工具做不到的。

唯一的缺点是darglint的配置项有点多，初次设置时容易晕。但只要写好一个.darglint配置文件放在项目根目录，后续就省心了。配置可以按项目需求灵活调整，比硬编码在代码里干净。

整体来说，darglint适合那些对代码文档质量有要求的项目。如果团队里文档只是copy paste，有没有无所谓，那这个工具的作用就不大。但如果你维护的是公共库或者API，darglint能让你少踩不少坑。