萬盛學電腦網

您现在的位置: 萬盛學電腦網 >> 程式設計 >  >> 網路程式設計 >> 程式語言綜合

Python 註解完整指南:單行、多行與文件字串最佳實務

單行註解

# 這是單行註解
print("Hello")  # 行尾註解

多行註解 (慣用三引號字串)

Python 無原生多行註解語法,社群慣例使用多行字串字面值 (未指派給變數),直譯器會忽略:

"""
這是多行註解區塊
第 2 行說明
第 3 行說明
"""
print("執行中...")

文件字串 — 正式文件化工具

模組、類別、函數首行的字串字面值會成為 __doc__ 屬性,支援 help()、pydoc、Sphinx 等工具提取:

def calculate_area(radius):
    """計算圓面積。

    Args:
        radius (float): 半徑

    Returns:
        float: 面積
    """
    return 3.14159 * radius ** 2

print(calculate_area.__doc__)

最佳實務建議

  • 單行:用 #,簡短說明「做什麼」或「為什麼」。
  • 多行區塊:用 """...""",暫時停用代碼或區塊說明。
  • 公開 API:必須撰寫文件字串 (遵循 NumPy/Google/pep257 風格)。
  • 型別提示:Python 3.5+ 建議搭配 typing 模組,減少註解說明型別需求。
  • 避免過度註解「顯而易見」的代碼,專注於業務邏輯、演算法意圖、副作用說明。

工具支援

  • IDE (VS Code, PyCharm) 自動產生文件字串模板。
  • flake8 + pydocstyle 檢查文件字串規範。
  • Sphinx 產生專案文件網站。
copyright © 萬盛學電腦網 all rights reserved