讓 AI 更懂你的程式碼：Python DocString 撰寫全攻略

DocString 的基本概念

DocString（文件字串）是 Python 中用於為模組、類、函數和方法等添加說明的字符串。它們通常使用三重引號（""" 或 '''）包圍，並放置在定義的首行。與普通注釋不同，DocString 在運行時會被保留，並可以通過程式訪問，這使其成為 Python 文檔系統的核心組成部分。

def square(n):
    """Take a number n and return the square of n."""
    return n**2

help(square)

在上述範例中，"""Take a number n and return the square of n."""就是函數square()的 DocString。

Help on function square in module __main__:
square(n)
Take a number n and return the square of n.

你可以透過help()函數或__doc__屬性來訪問 DocString。

print(square.__doc__)

以下是輸出結果：

Take a number n and return the square of n.

DocString 的優勢

使用 DocString 有許多顯著的優勢：提高代碼可讀性，使代碼更易於理解和維護；自動生成文檔，簡化文檔維護工作；運行時可訪問，通過__doc__屬性或help()函數獲取說明；標準化描述，保持代碼庫的一致性；多行語法支持，便於編寫詳細說明；提高協作效率，幫助團隊成員快速理解代碼。

此外，DocString 還有助於輔助調試和使用，便於開發和正確使用 API；遵循 DocString 標準規範（如 PEP 257）使代碼更專業，符合 Python 社區的最佳實踐。總的來說，DocString 不僅提高了代碼的質量和可維護性，還促進了團隊協作和知識共享，是 Python 開發中不可或缺的工具。

DocString 的類型與格式

根據使用場景和內容複雜度，DocString 可分為多種類型：

單行 DocString

適用於簡單、功能明確的函數或方法，僅需一行即可說明其用途。

def add(a, b):
    """返回兩數之和。"""
    return a + b

多行 DocString

適用於複雜的函數、類或模組，需要詳細說明其功能、參數、返回值等。

def complex_function(x, y):
    """
    執行一個複雜的計算。
    
    參數：
    x (int): 第一個數字。
    y (int): 第二個數字。
    
    返回：
    int: 計算結果。
    """
    return x * y + x - y

help(complex_function)

以下是輸出結果：

Help on function complex_function in module __main__:
complex_function(x, y)
執行一個複雜的計算。
參數：
x (int): 第一個數字。
y (int): 第二個數字。
返回：
int: 計算結果。

模組級 DocString

放在模組文件的開頭，用於說明整個模組的功能和組件。

"""
這個模組包含處理數學運算的函數。
"""

def add(a, b):
    """返回兩數之和。"""
    return a + b

類級 DocString

放在類定義的第一行，說明類的用途和特性。

class Calculator:
    """一個簡單的計算器類。"""
    
    def add(self, a, b):
        """返回兩數之和。"""
        return a + b

help(Calculator)

以下是輸出結果：

Help on class Calculator in module __main__:
class Calculator(builtins.object)
| 一個簡單的計算器類。
|
| Methods defined here:
|
| add(self, a, b)
| 返回兩數之和。
|
| ----------------------------------------------------------------------
| Data descriptors defined here:
|
| __dict__
| dictionary for instance variables
|
| __weakref__
| list of weak references to the object

DocString 的編寫規範

Python 社區已建立多種 DocString 編寫規範，以確保文檔的一致性和可讀性：

PEP 257 規範

PEP 257 是 Python 官方的 DocString 規範，提供了全面的編寫指導。它旨在標準化 DocString 的格式，以提高代碼的一致性和可讀性。主要原則包括：

• 使用三重引號（"""）包裹 DocString，即使是單行描述
• 首行應為簡潔的摘要，概括模組、類或函數的主要功能
• 多行 DocString 的首行後應空一行，以視覺上分隔摘要和詳細描述
• DocString 的內容應與代碼塊的縮進保持一致，確保格式整潔
• 對於函數和方法，應描述其行為而非實現細節
• 盡可能使用動詞短語描述函數的作用，例如”計算平均值”而非”計算平均值的函數”

這些規範有助於創建清晰、統一的文檔，便於其他開發者理解和使用你的代碼。

詳細的 PEP 257 規範可在 Python 官方文檔 中查閱。

AI 時代的 DocString 寫法進化

在 AI 輔助開發逐漸普及的今天，像是 GitHub Copilot、ChatGPT 等工具會依賴 DocString 來理解程式的語意與結構。這代表我們不僅在寫給人看，更是在為 AI 撰寫 Prompt。一份寫得好的 DocString，能大幅提升 AI 的補全品質與建議準確度。

明確描述函式「做什麼」而非「怎麼做」

避免使用模糊描述，例如「處理資料」、「進行計算」等，改用具體語句說明功能與目的：

def calculate_tax(amount, rate):
    """
    根據稅率計算總金額。

    參數：
    amount (float): 原始金額。
    rate (float): 稅率（如 0.05 表示 5%）。

    返回：
    float: 含稅後金額。
    """
    return amount * (1 + rate)

這樣寫的優點是，AI 可以直接理解到函數的用途，而不需要去分析代碼。

提供清楚的輸入與輸出型別資訊

動態語言如 Python，AI 工具需靠 DocString 協助進行型別推理：

def get_user_profile(user_id):
    """
    根據使用者 ID 取得個人資料。

    參數：
    user_id (str): 使用者唯一識別碼。

    返回：
    dict: 包含 name、email、created_at 的使用者資料。
    """
    pass

這樣寫的優點是，AI 可以直接理解到函數的輸入與輸出型別，而不需要去分析代碼。

指明異常與邊界條件

這有助於 AI 在自動補全時加上例外處理邏輯：

def divide(a, b):
    """
    將 a 除以 b。

    拋出：
    ValueError: 若 b 為 0。
    """
    if b == 0:
        raise ValueError("除數不可為 0")
    return a / b

這樣寫的優點是，AI 可以直接理解到函數的異常處理邏輯，而不需要去分析代碼。

採用 AI 熟悉的格式（如 Google、Numpydoc）

這些格式在語料中頻繁出現，AI 模型較容易解析內容結構，推薦選擇並保持一致性。

Google 風格 DocString

Google 風格的 DocString 強調可讀性和簡潔性，廣泛用於 Google 的 Python 專案中。這種風格特點包括：

1. 簡潔的摘要行
2. 參數、返回值和異常使用特定的格式
3. 可選的擴展描述

範例：

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """
    pass

這種風格的 DocString 易於閱讀和維護，同時提供了足夠的細節來理解函數的用途和使用方法。

Numpydoc 風格 DocString

科學和數據分析社區廣泛使用的風格，是 Google 風格的擴展，為參數和返回值提供了額外的約定。

def divide_numbers(a, b):
    """
    Divide two numbers.
    
    Parameters
    ----------
    a : float
        The dividend.
    b : float
        The divisor.
    
    Returns
    -------
    float
        The quotient of the division.
    """
    if b == 0:
        raise ValueError("Division by zero is not allowed.")
    return a / b

結論

DocString 是 Python 程式中不可或缺的文檔工具，它不僅提高了代碼的可讀性和可維護性，也促進了團隊協作和知識共享。通過遵循標準規範編寫 DocString，開發者可以創建更專業、更高質量的代碼。

根據 Stack Overflow 的 2023 年調查，78% 的專業開發者認為文檔對於日常工作至關重要。然而，只有 32% 的受訪者表示在項目中始終使用 DocString。這一差距表明，掌握並善用 DocString 技術，將為開發者帶來顯著的職業優勢。

在 Python 編程實踐中，養成編寫清晰、全面的 DocString 的習慣，將使您的代碼更加專業，也使您在團隊協作中更具價值。