文檔是非常重要的,不僅可以與其他人溝通函數/類/方法/模塊的目標,也可以幫助自己記住這些知識。
當你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
這些標準允許使用工具提取文檔字符串,並自動為代碼生成文檔。