Python中docstring文档的写法

该写法根据Python的PEP 257文档总结。
类的函数称为方法(method),模块里的函数称为函数(function)

  1. 每一个包,模块,类,函数,方法都应该包含文档,包括类的__init__方法
  2. 包的文档写在__init__.py文件中
  3. 文档有单行文档和多行文档
  4. 单行文档:
    1. 不要重复函数的声明语句,例如:function(a, b) -> list
    2. 指明做什么和返回什么,例如Do X and return a list.
    3. 使用三引号,方便换行
  5. 多行文档:
    1. 如果模块是一个脚本,也就是单文件程序,模块的文档应该写明脚本的使用方法
    2. 模块的文档需要写明包含的类,异常,函数
    3. 如果是包,在__init__.py中,写明包里面包含的模块,子包
    4. 如果是函数或类方法,应该写明函数或方法的作用,参数,返回,副作用,异常和调用的限制等
    5. 如果是类,写明类的行为,和实例参数,构造方法写在__init__中
    6. 使用三引号,而且两个三引号都应该单独成行

单行例子:

def function(a, b):
    """Do X and return a list."""

多行例子:

def complex(real=0.0, imag=0.0):
    """Form a complex number.
    Keyword arguments:
    real -- the real part (default 0.0)
    imag -- the imaginary part (default 0.0)
    """
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

未经许可请不要转载。

posted on   ExplorerMan  阅读(3256)  评论(1编辑  收藏  举报

导航

< 2025年1月 >
29 30 31 1 2 3 4
5 6 7 8 9 10 11
12 13 14 15 16 17 18
19 20 21 22 23 24 25
26 27 28 29 30 31 1
2 3 4 5 6 7 8
点击右上角即可分享
微信分享提示