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