Python - 文档字符串 (Docstrings)

大家好，有抱负的Python程序员們！今天，我們將深入探討精彩的文档字符串世界。作為你友善的鄰居電腦科學老師，我非常高興能引導你們通過這個Python編程的關鍵部分。所以，拿起你喜歡的飲料，放鬆一下，讓我們一起踏上這個學習冒險之旅！

Python - Docstrings

Python中的文档字符串

想象一下你在寫日記。在每篇日記的開頭，你可能會草草地寫下那天發生了什麼的簡要概述。嗯，Python中的文档字符串有點像那樣！它們是特殊的字符串，描述了一段代碼的功能，讓你（和其他人）在稍後更容易理解你的代碼。

在Python中，文档字符串被三重引號（""" 或 '''）包圍，並放在函數、類或模塊定義之後。讓我們看一個簡單的例子：

def greet(name):
"""此函數對作為參數傳入的人表示問候"""
print(f"Hello, {name}!")

在這個例子中，三重引號之間的行是我們的文档字符串。它簡要解釋了greet函數的功能。

單行文档字符串

對於簡單的函數或類，一個單行文档字符串可能就是你需要的。這裡有另一個例子：

def square(n):
"""返回一個數字的平方。"""
return n ** 2

這個文档字符串簡潔而精闢，只用一行就告訴了我們該函數的功能。

多行文档字符串

對於更複雜的函數或類，你可能需要一個多行文档字符串。這些通常包括一個概要行，後面是一個空行，然後是更詳細的信息。讓我們看看一個例子：

def calculate_area(length, width):
"""
計算矩形的面積。

參數：
length (float): 矩形的長度
width (float): 矩形的寬度

返回：
float: 矩形的面積
"""
return length * width

這個多行文档字符串提供了有關函數參數和返回值的更多詳細信息。

模塊的文档字符串

模塊也可以有文档字符串！這些放在文件的開頭。例如：

"""
此模塊包含幾何計算的實用函數。
它包括用於計算各種形狀的面積和體積的函數。
"""

def calculate_circle_area(radius):
# 函數實現在這裡

類的文档字符串

類也可以有文档字符串。這些放在類定義之後：

class Rectangle:
"""
類表示矩形。

屬性：
length (float): 矩形的長度
width (float): 矩形的寬度
"""

def __init__(self, length, width):
self.length = length
self.width = width

訪問文档字符串

文档字符串的一個很酷的地方是你可以編程訪問它們。Python將文档字符串存儲為函數、類或模塊的__doc__屬性。以下是訪問它的方法：

def greet(name):
"""此函數對作為參數傳入的人表示問候"""
print(f"Hello, {name}!")

print(greet.__doc__)

這將輸出：此函數對作為參數傳入的人表示問候

寫文档字符串的最佳實踐

現在我們知道了如何撰寫文档字符串，來談談一些最佳實踐：

保持簡潔但提供信息
使用正確的語法和標點符號
在風格上保持一致
為函數提供參數和返回值的信息
為類描述重要的屬性和方法

Google風格的文档字符串

Google有自己的文档字符串風格指南。以下是一個例子：

def divide(a, b):
"""除以兩個數字。

參數：
a (int): 被除數。
b (int): 除數。

返回：
float: 除法的結果。

引發：
ZeroDivisionError: 如果b為0。
"""
if b == 0:
raise ZeroDivisionError("不能除以零")
return a / b

NumPy/SciPy風格的文档字符串

如果你正在使用科學Python庫，你可能会遇到NumPy/SciPy風格：

def calculate_mean(numbers):
"""
計算數字列表的算術平均值。

參數
----------
numbers : list
數字列表。

返回
-------
float
輸入列表的算術平均值。
"""
return sum(numbers) / len(numbers)

Sphinx風格的文档字符串

Sphinx是Python的一個流行的文檔生成器。其風格與reStructuredText格式相似：

def fibonacci(n):
"""
生成一個遞增序列達到n。

:param n: 要生成的遞增序列的數量
:type n: int
:return: 一個遞增序列
:rtype: list
"""
sequence = [0, 1]
while len(sequence) < n:
sequence.append(sequence[-1] + sequence[-2])
return sequence[:n]

文档字符串與註釋的區別

你可能會想知道，“文档字符串和普通註釋之間有什麼區別？”問得好！讓我們來分析一下：

語法：文档字符串使用三重引號，而註釋使用#。
放置位置：文档字符串放在定義之後，而註釋可以放在任何地方。
目的：文档字符串解釋代碼的功能，註釋解釋它是如何做到的。
可訪問性：文档字符串可以編程訪問，註釋則不行。

以下是一個簡單的例子來說明：

def add(a, b):
"""
將兩個數字相加並返回結果。
"""
# 這是一個解釋我們如何進行加法的註釋
return a + b  # 這是一個行內註釋

就這樣，各位！我們已經涵蓋了Python文档字符串的方方面面。請記住，良好的文檔就像為未來的你（或其他開發人員）留下的麵包屑一樣。現在可能看起來像是額外的工作，但相信我，你會後悔的！

以下是我們涵蓋的文檔字符串風格的快速參考表：

風格	摘要	示例
單行	簡要，一行描述	`"""返回一個數字的平方。"""`
多行	詳細描述，包括參數和返回值	`"""計算矩形的面積。\n\n參數：\n..."""`
Google	包含Args、Returns和Raises部分	`"""除以兩個數字。\n\n參數：\n..."""`
NumPy/SciPy	使用參數和返回部分，格式更詳細	`"""計算數字列表的算術平均值。\n\n參數\n----------\n..."""`
Sphinx	使用:param:、:type:、:return:和:rtype:字段	`"""生成一個遞增序列達到n。\n\n:param n: ..."""`

編程愉快，願你的文档字符串永遠清晰而富有信息！

Credits: Image by storyset