python文档字符串注释_Python docstring（文档字符串）：给代码添加注释

dcostring 是一种特殊类型的注释，可以把它放在一个函数或类定义之后，或者一个文件的开头，其功能是说明函数、类或者模块是做什么的。

docstring 可以用三个引号、单引号或者双引号括起来，如下所示：

class Test: '''测试 docstring 的类 ''' def __init__(self): '''Test类初始化对象,不需要任何参数 ''' self.num = 10 t = Test() help(t)

有读者可能会问，为什么不直接使用注释？因为 docstring 在 Python 中很特殊，有一些 Python 内建的函数，可以使用 docstring 来帮助其他程序员来使用你的代码。

运行上面程序，可以看到如下输出结果：

Help on Test in module __main__ object: class Test(builtins.object) | 测试 docstring 的类 | | Methods defined here: | | __init__(self) | Test类初始化对象,不需要任何参数 | | ---------------------------------------------------------------------- | Data descriptors defined here: | | __dict__ | dictionary for instance variables (if defined) | | __weakref__ | list of weak references to the object (if defined)

可以看到，help() 函数找到了所有的函数和 docstring，并且自动创建了一个格式漂亮的帮助页面。由此，用户不需要深入你的代码，就可以知道哪些函数可用，函数需要接受什么参数。

这里给初学者总结了适合写在 docstring 中的内容：

函数或者类、模板是干什么的；

对于类来说，它是否可以直接使用，或者它只是基类，不能单独使用；

用户期望从一个函数中返回什么；

在使用过程中，可能会给出的警告类型；

如果包含参数，则参数的值应该是什么数据类型。

注意，PEP 257 中包含了编写 docstring 的指南，感兴趣的读者可前往 Python PEP-0257 进行阅读。