在Python程式設計中，程式碼的可讀性和可維護性至關重要。除了清晰的命名和結構良好的程式碼外，良好的文件字串（docstring）也是確保程式碼易於理解和使用的關鍵工具。docstring是Python中用於記錄模組、類、方法和函式行為的字串，幫助開發者和使用者快速瞭解程式碼的功能和用法。本文將詳細介紹docstring的使用，包括如何編寫、格式化以及在不同的上下文中應用。
什麼是docstring
docstring是嵌入在Python程式碼中的文件字串，用於描述模組、類、函式或方法的功能。它通常放置在定義的程式碼塊內部，緊跟在def或class宣告之後。docstring是Python中獨特的文件工具，它不僅僅是註釋，還可以透過各種工具自動提取和顯示。
簡單的docstring
def greet(name):
"""返回一個問候資訊。
引數：
name (str): 被問候者的名字。
返回：
str: 問候資訊。
"""
return f"Hello, {name}!"
在這個示例中，greet函式的docstring描述了函式的用途、引數以及返回值。
docstring的基本語法和格式
docstring通常使用三重引號"""或'''來定義，這允許文件字串跨多行書寫。為了確保docstring的可讀性，通常會遵循一定的格式和標準。
多行docstring
def calculate_area(radius):
"""計算圓的面積。
這是一個多行docstring示例。
可以在這裡詳細描述函式的行為和注意事項。
引數：
radius (float): 圓的半徑。
返回：
float: 圓的面積。
"""
import math
return math.pi * radius ** 2
在這個示例中，docstring不僅描述了函式的功能，還包含了關於引數和返回值的詳細資訊。
docstring的標準格式
Python社群廣泛使用幾種docstring格式標準，其中最常見的是Google風格、NumPy風格和reStructuredText（reST）風格。這些標準幫助開發者編寫一致且結構化的文件。
Google風格的docstring
Google風格的docstring使用簡潔的格式，分為描述、引數和返回值等部分。
def add(x, y):
"""計算兩個數的和。
Args:
x (int or float): 第一個數。
y (int or float): 第二個數。
Returns:
int or float: 兩個數的和。
"""
return x + y
NumPy風格的docstring
NumPy風格的docstring更詳細，通常用於科學計算和資料分析的庫。
def multiply(a, b):
"""
計算兩個數的乘積。
Parameters
----------
a : int or float
第一個數。
b : int or float
第二個數。
Returns
-------
int or float
兩個數的乘積。
"""
return a * b
reStructuredText（reST）風格的docstring
reST風格的docstring通常與Sphinx等文件生成工具一起使用，支援豐富的格式化選項。
def divide(x, y):
"""
計算兩個數的商。
:param x: 被除數。
:type x: int or float
:param y: 除數。
:type y: int or float
:return: 商。
:rtype: float
:raises ZeroDivisionError: 當除數為零時丟擲。
"""
if y == 0:
raise ZeroDivisionError("除數不能為零")
return x / y
docstring在不同上下文中的應用
模組級docstring
模組級docstring用於描述整個模組的用途和內容，通常放在模組的頂部。
"""
math_operations模組
這個模組提供了簡單的數學運算函式，包括加法、減法、乘法和除法。
"""
def add(x, y):
"""計算兩個數的和。"""
return x + y
def subtract(x, y):
"""計算兩個數的差。"""
return x - y
類級docstring
類級docstring用於描述類的功能、用法以及類中包含的主要方法。
class Calculator:
"""一個簡單的計算器類。
這個類提供了基本的數學運算功能，包括加法和減法。
"""
def add(self, x, y):
"""計算兩個數的和。"""
return x + y
def subtract(self, x, y):
"""計算兩個數的差。"""
return x - y
函式和方法級docstring
函式和方法級docstring是最常見的形式，用於描述函式或方法的功能、引數、返回值以及異常處理。
def multiply(x, y):
"""計算兩個數的乘積。
引數：
x (int or float): 第一個數。
y (int or float): 第二個數。
返回：
int or float: 兩個數的乘積。
"""
return x * y
如何提取和使用docstring
Python內建了help()函式和__doc__屬性，可以輕鬆提取docstring。docstring還可以用於自動生成文件，配合工具如Sphinx使用。
使用help()函式檢視docstring
def subtract(x, y):
"""計算兩個數的差。"""
return x - y
help(subtract)
輸出：
Help on function subtract in module __main__:
subtract(x, y)
計算兩個數的差。
使用__doc__屬性
def divide(x, y):
"""計算兩個數的商。"""
return x / y
print(divide.__doc__)
輸出：
計算兩個數的商。
docstring的最佳實踐
簡潔明瞭：docstring應清晰簡潔地描述程式碼的功能，不宜過於冗長。
覆蓋所有重要資訊：包括函式的功能、引數、返回值、異常等。
遵循格式標準：選擇適合的格式標準，如Google風格、NumPy風格或reST風格，並在整個專案中保持一致。
避免與程式碼重複：docstring應補充程式碼的理解，而不是重複程式碼內容。
綜合應用的docstring
def calculate_statistics(data):
"""計算給定資料集的基本統計量。
該函式返回資料集的平均值、中位數和標準差。
引數：
data (list of float): 一個包含數值的列表。
返回：
dict: 包含'average'，'median'和'std_dev'鍵的字典，分別對應平均值、中位數和標準差。
異常：
ValueError: 當資料集為空時丟擲。
"""
if not data:
raise ValueError("資料集不能為空")
average = sum(data) / len(data)
median = sorted(data)[len(data) // 2]
variance = sum((x - average) ** 2 for x in data) / len(data)
std_dev = variance ** 0.5
return {"average": average, "median": median, "std_dev": std_dev}
在這個示例中，docstring詳細描述了函式的功能、引數、返回值以及可能引發的異常。
https://www.70zhan.com
總結
本文詳細探討了Python中docstring的使用方法及其在提升程式碼可讀性和可維護性方面的重要性。透過具體的示例，介紹瞭如何在模組、類、函式和方法中編寫清晰、簡潔的docstring，以及如何使用不同的格式標準如Google風格、NumPy風格和reST風格來組織文件內容。還展示瞭如何使用Python內建工具提取和檢視docstring，並討論了編寫docstring的最佳實踐。掌握這些技巧，將幫助大家建立自帶說明書的程式碼，使Python專案更易於理解和維護。