/

Python Docstrings

Python Docstrings

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

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

註釋（Comments）是一種方式：

1
2
# 這是一個註釋
num = 1 #這是另一個註釋

另一種方式是使用文檔字符串（docstrings）。

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

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

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

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

1
2
3
4
5
6
7
8
9
10
class Dog:
 """表示一只狗的類"""
 def __init__(self, name, age):
 """初始化一只新狗"""
 self.name = name
 self.age = age

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

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
"""狗模塊

這個模塊做...佈拉佈拉佈拉，並提供以下類：

- Dog
...
"""

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

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

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

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

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

例如，調用help(increment)將獲得這個：

1
2
3
4
5
在模塊__main__中的增量函數的幫助：

增量(n)
 增加
 一個數字

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

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

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

tags: [“Python”, “docstrings”, “documentation”, “coding conventions”]