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 进行阅读。