文檔是非常重要的,不僅可以與其他人溝通函數/類/方法/模塊的目標,也可以幫助自己記住這些知識。

當你6個月或12個月後回到你的代碼時,你可能不記得心中所保存的所有知識,通讀代碼並理解其目的將變得困難得多。

註釋(Comments)是一種方式:


num = 1 #這是另一個註釋

另一種方式是使用文檔字符串(docstrings)

文檔字符串的好處在於它們遵循慣例,因此可以自動處理。

這是如何為函數定義文檔字符串:

def increment(n):
 """增加一個數字"""
 return n + 1

這是如何為類和方法定義文檔字符串:

class Dog:
 """表示一只狗的類"""
 def __init__(self, name, age):
 """初始化一只新狗"""
 self.name = name
 self.age = age

 def bark(self):
 """讓狗叫"""
 print('WOF!')

通過在文件頂部放置一個文檔字符串來為模塊進行文檔,例如假設這是dog.py

"""狗模塊

這個模塊做...佈拉佈拉佈拉,並提供以下類:

- Dog
...
"""

class Dog:
 """表示一只狗的類"""
 def __init__(self, name, age):
 """初始化一只新狗"""
 self.name = name
 self.age = age

 def bark(self):
 """讓狗叫"""
 print('WOF!')

文檔字符串可以跨越多行:

def increment(n):
 """增加
 一個數字
 """
 return n + 1

Python會處理這些文檔字符串,你可以使用help()全局函數來獲取類/方法/函數/模塊的文檔。

例如,調用help(increment)將獲得這個:

在模塊__main__中的增量函數的幫助:

增量(n)
 增加
 一個數字

有很多不同的格式化文檔字符串的標準,你可以選擇遵循自己喜歡的標準。

我喜歡Google的標準:https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

這些標準允許使用工具提取文檔字符串,並自動為代碼生成文檔。