Python 程式設計的世界

【Python 的 docstring 完全指南】撰寫方式、風格與最佳實踐

例外與錯誤處理
目次

1. 什麼是 Python 的 docstring？

在 Python 中，docstring 是一種特殊的字串，用於為函式、類別或模組等程式碼添加說明。docstring 能提升程式碼的可維護性，使其他開發人員更容易理解你的程式碼。此外，透過後續介紹的自動文件生成工具（例如：Sphinx），可以利用 docstring 來建立完整的文件。

docstring 的位置與格式

docstring 一般放置於函式、類別或模組的定義之後，並以三重雙引號包圍，這是其基本格式。常見的語法如下：
def 函式名稱(參數):
    """
    在這裡撰寫函式的簡要說明。

    參數:
        參數名稱 (型別): 參數的詳細說明
    回傳值:
        型別: 回傳值的說明
    """
    pass
docstring 也可用於 Python 內建函式 help()，以及編輯器中的輔助顯示，對於程式碼的文件化具有極為重要的作用。

2. docstring 的基本寫法

Python 的 docstring 主要用於簡潔且清晰地說明函式或類別的功能。通常，首先簡單描述函式的目的，接著說明參數、回傳值與可能的錯誤。遵循 Python 官方風格指南 PEP 257，可以確保文件的一致性，使其他開發人員更容易理解。

基本的 docstring 結構

單行 docstring 適用於簡單的函式，用來簡要說明函式的功能，例如：
def add(a, b):
    """回傳兩個數值的總和。"""
    return a + b
多行 docstring 則用於更詳細的描述，包括函式的行為、參數與回傳值，並透過換行提高可讀性。
def add(a, b):
    """
    計算兩個數值的總和並回傳結果。

    參數:
        a (int): 第一個數值
        b (int): 第二個數值

    回傳值:
        int: 兩個數值的總和
    """
    return a + b
 
年収訴求

3. docstring 的風格（Google 風格、NumPy 風格、reStructuredText 風格）

docstring 的風格取決於專案需求與使用的工具。主要有 Google 風格、NumPy 風格及 reStructuredText 風格三種常見格式。

Google 風格

Google 風格以簡潔且視覺清晰著稱。參數與回傳值使用 Args 與 Returns 區塊標示，使函式說明更容易理解。
def add(a, b):
    """
    計算兩個數值的總和並回傳結果。

    Args:
        a (int): 第一個數值
        b (int): 第二個數值

    Returns:
        int: 兩個數值的總和
    """
    return a + b

NumPy 風格

NumPy 風格適用於提供更詳細說明，特別是在科學計算與數據分析相關的專案中。使用 Parameters 與 Returns 標示參數與回傳值的詳細資訊。
def add(a, b):
    """
    計算兩個數值的總和並回傳結果。

    Parameters
    ----------
    a : int
        第一個數值
    b : int
        第二個數值

    Returns
    -------
    int
        兩個數值的總和
    """
    return a + b

reStructuredText 風格

reStructuredText 風格適用於 Sphinx 這類文件生成工具，常用於大型專案中。Sphinx 會使用此風格來自動生成 HTML 或 PDF 文件。
def add(a, b):
    """
    計算兩個數值的總和。

    :param a: 第一個數值
    :type a: int
    :param b: 第二個數值
    :type b: int
    :return: 兩個數值的總和
    :rtype: int
    """
    return a + b
 

4. PEP 257 與最佳實踐

Python 官方風格指南 PEP 257 提供了 docstring 的標準寫法，遵循這些指南可以提升程式碼的可讀性，使團隊協作更加順暢。

PEP 257 的重要原則

  1. 單行 docstring 簡單的函式應使用單行 docstring，簡要描述函式的功能。
  2. 多行 docstring 需要更詳細的說明時，應使用多行 docstring，首行提供簡短摘要，接著換行後詳細說明。
  3. 縮排與換行 應使用適當的縮排與換行來提高可讀性，並確保參數與回傳值的資訊清晰易讀。

最佳實踐

  • 簡潔且清楚的描述 docstring 應該簡單明瞭，準確描述函式或類別的用途，避免冗長或含糊的說明。
  • 保持風格一致 專案應選擇適合的 docstring 風格（如 Google 風格或 NumPy 風格），並保持一致性，以提升可讀性與維護性。

5. 使用 docstring 進行測試（doctest）

Python 提供了一個內建的 doctest 模組，可用來測試 docstring 內的範例程式碼是否按照預期執行。透過 doctest，可以確保文件中的程式碼是正確的，並提高程式的可信度。

doctest 的基本用法

doctest 會自動偵測 docstring 內的範例程式碼，並驗證其輸出是否符合預期。可以在 if __name__ == "__main__": 區塊內加入 doctest 來執行測試，如下所示：
def add(a, b):
    """
    計算兩個數值的總和並回傳結果。

    Args:
        a (int): 第一個數值
        b (int): 第二個數值

    Returns:
        int: 兩個數值的總和

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()
在這個範例中，doctest 會執行 docstring 內的範例測試。如果測試通過，則不會顯示任何輸出；若測試失敗，則會顯示錯誤資訊，幫助開發人員發現問題。

使用 doctest 的優勢

  1. 確保文件與程式碼的一致性 透過 doctest，可以確保 docstring 內的範例程式碼是可執行且正確的，避免文件與實際程式碼不符。
  2. 簡化測試流程 doctest 提供了一種簡單的方法來測試函式的輸出結果，減少手動測試的負擔。
  3. 提高程式的可維護性 透過 doctest，可以輕鬆檢測程式碼的變更是否影響既有的功能，使程式更容易維護。

6. 實際範例：利用 docstring 進行文件化

透過 docstring，Python 程式碼的可讀性可以大幅提升，讓其他開發人員更容易理解程式的用途。本節將介紹如何在類別與函式中正確使用 docstring，並使用 Sphinx 自動生成文件。

為類別撰寫 docstring

為類別與方法添加 docstring，可以讓程式碼更具可讀性與結構化。以下是一個簡單的類別範例：
class Calculator:
    """
    簡單的計算機類別。

    此類別提供基本的加法、減法、乘法與除法運算。

    Attributes:
        result (int): 用於儲存計算結果的變數
    """

    def __init__(self):
        """
        Calculator 類別的建構函式。
        初始化時將結果設為 0。
        """
        self.result = 0

    def add(self, a, b):
        """
        計算兩個數值的總和並回傳結果。

        Args:
            a (int): 第一個數值
            b (int): 第二個數值

        Returns:
            int: 兩個數值的總和
        """
        self.result = a + b
        return self.result
在這個範例中，類別的 docstring 描述了其用途與屬性，而每個方法的 docstring 則提供了詳細的功能說明，使開發者更容易理解與使用該類別。

使用 Sphinx 自動生成文件

Sphinx 是 Python 常用的文件生成工具，可根據 docstring 自動產生 HTML 或 PDF 格式的文件。要使用 Sphinx，首先需要安裝它：
pip install sphinx
然後使用 sphinx-quickstart 初始化專案，接著透過 make html 命令生成對應的文件。

7. 常見錯誤與避免方法

在撰寫 docstring 時，初學者經常會犯一些錯誤。本節將介紹幾個常見的錯誤類型以及如何避免這些錯誤。

1. 說明內容過於模糊

docstring 應該清楚描述函式的功能，避免含糊不清的說明。例如，以下的 docstring 太過簡略，沒有提供足夠的資訊：
def add(a, b):
    """將兩個數字相加。"""
    return a + b
這樣的說明並未提供輸入與回傳值的類型資訊，容易造成理解上的困難。正確的寫法應該像這樣：
def add(a, b):
    """
    計算兩個數值的總和並回傳結果。

    Args:
        a (int): 第一個數值
        b (int): 第二個數值

    Returns:
        int: 兩個數值的總和
    """
    return a + b

2. 未明確說明參數與回傳值

當 docstring 省略參數與回傳值的資訊時，使用者可能無法正確理解函式的行為。例如：
def divide(a, b):
    """執行除法運算。"""
    return a / b
這個說明並沒有提到數值類型，也沒有說明如果除數為 0 會發生什麼錯誤。以下是更好的寫法：
def divide(a, b):
    """
    計算 a 除以 b 的結果。

    Args:
        a (float): 被除數
        b (float): 除數，不能為 0

    Returns:
        float: 除法結果

    Raises:
        ZeroDivisionError: 當 b 為 0 時拋出錯誤
    """
    if b == 0:
        raise ZeroDivisionError("除數不能為 0")
    return a / b

8. 總結：利用 docstring 高效撰寫文件

在本篇文章中，我們介紹了 Python 的 docstring 及其重要性，包括如何撰寫、不同的風格、最佳實踐以及如何使用 doctest 進行測試。此外，我們還探討了如何利用 Sphinx 自動生成文件。

PEP 257 標準化文件風格

PEP 257 提供了 docstring 的官方指南，遵循這些標準可以提升文件的一致性與可讀性。使用單行 docstring 處理簡單函式，而較複雜的函式則應使用多行 docstring 來詳細說明。

透過 doctest 進行範例測試

透過 doctest，可以驗證 docstring 內的範例程式碼是否符合預期，確保文件內容與實際行為一致，並減少錯誤。

使用 Sphinx 自動生成文件

利用 Sphinx 等文件生成工具，可以根據 docstring 自動建立 HTML 或 PDF 格式的文件，大幅減少手動維護文件的時間，提高開發效率。 透過良好的 docstring 寫作習慣，不僅能提升程式碼的可讀性，也能讓開發團隊更輕鬆地協作與維護專案。