python dockle

## 关于Python Docstring，你可能需要知道这些

写代码这件事，有时候挺有意思的。刚开始学编程的时候，大家关注的都是语法对不对、功能能不能跑起来。等真正开始做项目，特别是和别人协作的时候，才会发现有些东西比语法本身更重要。Docstring就是其中之一。

它到底是什么

Docstring不是注释，虽然看起来都是用文字说明代码。注释是给维护代码的人看的，解释某行代码为什么这么写，或者某个复杂的逻辑是怎么回事。而Docstring是代码的一部分，它描述的是函数、类、模块本身是做什么的、怎么用。

可以把它想象成产品的说明书。你买了个家电，说明书不会告诉你里面的电路板是怎么焊接的，但会告诉你怎么开机、有哪些功能、每个按钮是干什么的。Docstring也是这样，它不关心函数内部的具体实现细节，而是告诉使用者这个函数是干什么的、需要什么参数、会返回什么结果。

Python里的Docstring很特别，它是放在三引号里的字符串，紧跟在函数、类或模块的定义之后。这个位置很关键，因为Python解释器会把它当作对象的一个特殊属性（__doc__）保存起来。这意味着你可以在运行时访问它，这是普通注释做不到的。

它能解决什么问题

最直接的作用当然是文档。打开一个几个月前写的函数，如果没有Docstring，可能得花好几分钟重新理解当时的思路。如果有清晰的Docstring，几秒钟就能想起来这个函数是干什么的、该怎么用。

但它的价值远不止于此。好的IDE和编辑器能直接显示Docstring，你在调用函数的时候，不用跳转到定义处就能看到参数说明。一些文档生成工具（比如Sphinx）可以直接从Docstring生成漂亮的HTML文档。还有些工具能用Docstring来做自动化测试。

更重要的是，写Docstring的过程本身就是在设计接口。当你认真思考这个函数应该怎么描述、参数怎么命名、返回值是什么的时候，其实是在从使用者的角度审视自己的设计。很多时候，写着写着就会发现原来的设计有问题，需要调整。

实际使用中的样子

Python社区有几个主流的Docstring风格，PEP 257是最基础的规范，但实际项目中更常见的是Google风格、NumPy风格或者reStructuredText风格。

Google风格的Docstring比较简洁，可读性好：

defcalculate_discount(price,discount_rate):""" 计算商品折扣后的价格。 Args: price: 商品原价，必须是正数 discount_rate: 折扣率，0到1之间的小数 Returns: 折扣后的价格 Raises: ValueError: 如果价格不是正数，或者折扣率不在0到1之间 """ifprice<=0:raiseValueError("价格必须是正数")ifnot0<=discount_rate<=1:raiseValueError("折扣率必须在0到1之间")returnprice*(1-discount_rate)

NumPy风格更详细一些，适合科学计算这类需要详细说明的场景。选择哪种风格主要看团队习惯和项目类型，关键是要保持一致。

写Docstring的时候有个小技巧：先写接口再写实现。也就是说，先定义好函数名、参数，然后马上写Docstring，最后才写函数体。这样能强迫自己先想清楚这个函数应该怎么用，而不是一头扎进实现细节里。

一些值得注意的细节

Docstring的第一行通常是个简短的总结，单独成行。这一行很重要，很多工具只显示这一行。详细的说明放在后面。

参数说明不仅要写类型，最好也写约束条件。比如“必须是正数”、“列表不能为空”这类信息，对使用者很有帮助。

对于复杂的函数，可以加一些使用示例。这些示例最好是能直接复制运行的代码，这样使用者可以最快地理解怎么用。

更新代码的时候别忘了更新Docstring。有时候改了几行代码，函数的逻辑变了，但Docstring没改，这种不一致比没有文档更糟糕。

和其他文档方式的区别

和注释相比，Docstring更结构化、更正式。注释可以很随意，可以写“这里有个bug需要修复”，但Docstring应该只描述接口本身。

和外部文档相比，Docstring的最大优势是离代码近。代码改了，如果开发者有好的习惯，Docstring会一起改。而单独的文档很容易和代码脱节。

有些语言用注解（annotation）来做类似的事情，Python的类型提示（type hints）也能提供一部分信息。但类型提示主要描述类型，Docstring可以包含更丰富的描述，比如参数的含义、边界条件、使用示例等。两者是互补的，不是替代关系。

真正重要的是，Docstring不是写完就完事的装饰品。它是代码的一部分，应该和代码一样被认真对待。好的Docstring能让代码更容易理解、更容易维护，最终节省的是整个团队的时间。

写代码就像写信，不仅要自己能看懂，还要让几个月后的自己、让团队里的其他人也能看懂。Docstring就是那封写给未来读者的信里，最重要的部分。