Python中docstring文件的寫法
阿新 • • 發佈:2018-12-27
該寫法根據Python的PEP 257文件總結。
類的函式稱為方法(method),模組裡的函式稱為函式(function)
- 每一個包,模組,類,函式,方法都應該包含文件,包括類的__init__方法
- 包的文件寫在__init__.py檔案中
- 文件有單行文件和多行文件
- 單行文件:
- 不要重複函式的宣告語句,例如:function(a, b) -> list
- 指明做什麼和返回什麼,例如Do X and return a list.
- 使用三引號,方便換行
- 多行文件:
- 如果模組是一個指令碼,也就是單檔案程式,模組的文件應該寫明指令碼的使用方法
- 模組的文件需要寫明包含的類,異常,函式
- 如果是包,在__init__.py中,寫明包裡面包含的模組,子包
- 如果是函式或類方法,應該寫明函式或方法的作用,引數,返回,副作用,異常和呼叫的限制等
- 如果是類,寫明類的行為,和例項引數,構造方法寫在__init__中
- 使用三引號,而且兩個三引號都應該單獨成行
單行例子:
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 ...
未經許可請不要轉載。