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

作者: Calpa Liu
字數:1969
出版:2025 年 4 月 18 日
在 AI 輔助開發時代,清晰的程式文件不只是寫給人看的,更是讓 AI 工具正確理解你程式碼的關鍵。本文深入解析 Python DocString 的撰寫方式與實用範例,包含 PEP 257、Google 風格與 Numpydoc 樣式,幫助你打造對開發者與 AI 都友善的專業程式碼註解。

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 的習慣,將使您的代碼更加專業,也使您在團隊協作中更具價值。

關於 Calpa

Calpa 擅長使用 TypeScriptReact.jsVue.js 建立 Responsive Website。

他積極參與開源社區,曾在 2019 年的香港開源大會上擔任講者,提供工作經驗和見解。此外,他也在 GitHub 上公開分享個人博客程式碼,已獲得超過 300 顆星星和 60 個分支的支持。

他熱愛學習新技術,並樂意分享經驗。他相信,唯有不斷學習才能跟上快速演變的技術環境。

熱門文章

最新文章

圖片管理中心
管理圖片資源
IP 查詢
快速查詢和定位 IP 地址的地理位置和相關信息
Python 運行器
無需後端、無需登入,只需打開瀏覽器即可運行 Python 代碼(由 Pyodide 提供支持)
封面圖生成器
自動創建適合各種平台的文章封面圖
原作(青山剛昌)產生器
一鍵創建原作(青山剛昌)的封面圖
日本色彩
探索和使用傳統日本色彩
部落格內容洞察儀表板
以視覺化儀表板方式追蹤文章成效、分享熱度與分類分布,協助創作者掌握內容表現。
蒙特卡羅估算 π
使用蒙特卡羅方法演示 π 值的估算過程
LLM
使用 LLM 模型進行聊天
活動圖生成器
一鍵創建活動的封面圖
Wagmi Card
一鍵創建 Wagmi 的封面圖
Facebook Quote
Facebook Quote
Music Macro Language (MML) Studio
用程式語法編寫旋律,用音符構築想像
Blurhash
一鍵創建 Blurhash
文字分類器
使用 MediaPipe TextClassifier 分類文字
前端工程師免費工具資源
前端工程師免費工具資源
後端工程師免費工具資源
後端工程師免費工具資源
全端工程師免費工具資源
全端工程師免費工具資源
Web3 工程師免費工具資源
Web3 工程師免費工具資源
紫微斗數排盤系統|結合 AI 的命盤性格與事業財務分析生成器
紫微斗數排盤工具,輸入生日與時辰,自動生成完整命盤分析提示(Prompt)。結合最專業紫微理論與 AI 助力,助你深入解析性格、事業、財務與人際課題。免費使用,適合命理師及紫微愛好者。
PixAI Prompt 組合器|快速打造可用於 AI 繪圖的語言拼圖
使用 PixAI 卻不會寫 prompt?這個工具幫你一鍵組裝角色、表情、風格語彙,輸出高品質繪圖提示語句(Prompt),可直接貼入 PixAI 使用。適合插畫師、創作者、AI 新手與 VTuber 角色開發者。