Python 多行註解與文件字串完整指南：三引號、單行 #、IDE 折疊區塊與最佳實務

Python **無原生多行註解語法** (如 C /* ... */)，但慣用三引號字串字面值達成同樣效果，並兼具文件字串功能。本文釐清三引號與 # 的語意差異、PEP 257 文件字串規範、IDE 區塊折疊技巧與專案級註解策略。

單行註解：#

# 這是單行註解
x = 1  # 行尾註解

• 解析器**完全忽略** # 至行尾內容。
• 適用於暫時停用程式碼、說明單行邏輯。

多行區塊：三引號字串 \"\"\" ... \"\"\" 或 ''' ... '''

"""
這是多行註解區塊
第 2 行
第 3 行
"""

• **語意上是字串字面值**，若未指派給變數/屬性，執行時會建立字串物件再立即捨棄 (極微小開銷)。
• **慣用為模組/類別/函數的文件字串** (docstring)，被 __doc__、help()、Sphinx 等工具提取。
• 縮排建議與外層程式碼對齊 (PEP 8)。

文件字串規範 (PEP 257)

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

    Args:
        user_id (int): 使用者唯一識別碼。

    Returns:
        dict: 使用者資料字典，找不到回傳 None。

    Raises:
        ValueError: user_id 非正整數。
    """
    if user_id <= 0:
        raise ValueError("user_id must be positive")
    # ...

• 單行 docstring："""做一件事。""" (結尾句點)。
• 多行 docstring：首行摘要、空行、詳細說明、參數/回傳/例外區塊。
• 使用 """ 而非 ''' (一致性)。

IDE 區塊折疊與區域標記

主流 IDE (PyCharm, VS Code, Spyder) 支援以註解標記折疊區域：

# region 資料庫連線設定
DB_HOST = "localhost"
DB_PORT = 5432
# endregion

# region 輔助函數
def helper(): ...
# endregion

• 非語言標準，但廣泛支援，提升大型檔案可讀性。
• VS Code 需安裝擴充套件 Fold Level 或內建 # region 支援 (1.60+)。

條件式註解：型別提示與型別檢查器

# type: ignore  # 告訴 mypy 忽略此行型別錯誤
x = some_dynamic_call()  # type: Any

專案級註解策略建議

常見誤區

1. 以為三引號是註解語法：實為字串字面值，若置於函數內部未指派，**仍會建立物件** (雖經優化可能消除)。
2. 巢狀三引號：""" outer """ inner """ """ 會在第一個配對處結束，避免巢狀。
3. 文件字串縮排不一致：導致 help() 顯示錯亂，遵循 PEP 8 縮排 4 空格。

遵循「公開介面寫 docstring，內部邏輯用 #，區塊折疊用 # region」，即可兼顧可讀性、工具支援與執行效能。

1. 上一篇文章： VB.NET DateTime 建構完全指南：四種實例化方式、軍用時間、預設值行為與 ToString 格式化
2. 下一篇文章： Java 執行 SQL 腳本 .bat 檔案：Runtime.exec 完整範例與同步等待、退出碼判斷

更多程式設計知識

無作業系統裸機運行 Python：Intel BITS 專案深度解析

在 PyCon 2015，Intel 工程師 Josh Tr

程式設計新手必讀：撰寫高品質技術文檔的完整指南

為什麼要寫技術文檔？ 六個月後的你會感謝現在的自己 從

Java 程序中 Hibernate 應用全景解析：原理、流程、三態、查詢與緩存

Hibernate 不只是工具，更是一種「對象思維操作數據庫

Python 分散式多進程實戰：跨機器任務佇列完整教學

當單機多進程無法滿足計算需求時，Python multipr