Python 註解 示範

許多程式語言官方並沒有要求要用兩個空格還是四個空格、程式碼中間有幾行空白等等，不過在 Python 中有列出詳細的官方建議，包含註解也是。

單行註解

    
# 這是一個註解
    

在 # 號和內容中間要有一個空格。

在 Python 官方的程式碼風格指南 中有提到一行程式碼中最多為 79 個字元，對於字串和註解則是 72 個字元(characters)。並且也有提到如果喜歡較長程式碼的團隊也可以將限制增加到 99 個字元，但是字串和註解還是 72 個字元。

並且官方也建議註解應該是完整的句子，首字母大寫，除非是以小寫開頭的特殊字母。並且非英語國家的軟體工程師也要使用英文寫註解，除非你 120% 確定程式碼不會有不講此語言的人閱讀。
註： 上面有提到官方建議註解要使用英文，在本文的範例中為了方便說明會使用中文註解

如果是與程式碼同一行的註解稱為行內註解(Inline Comments)，官方要求註解和程式碼要空兩格，並且盡量少用。

    
name = "Ruyut"  # 姓名
    

多行註解

筆者在官方文件中並沒有看到關於多行註解的規範，不過可以使用多行字串的方式，這些字串在執行時會被編譯，但是並不會實際被使用，可以用來充當多行註解

    
"""
這是
多行
註解
"""
    

文件註解(Docstring)

在模組(module)、函式(function)、類別(class)、方法(method)中的第一行可以使用下面的方式來定義註解：

    
def get_user_data_from_json(json_data):
    """從傳入的 json 中取得 使用者資料"""
    

在許多 IDE 中都可以快速查看註解，下圖是筆者常用的開發工具 PyCharm 的顯示範例：

如果有多行可以看下面的範例：

    
def get_user_data_from_json(json_data: str) -> User:
    """
    從傳入的 json 中取得 使用者資料
    :param json_data: json 格式的使用者資料
    :return: 使用者資料
    """
    

在上面可以看到 :return: 這樣特殊的文字，並且在顯示中會有特殊的顯示方式，不過這個並不是 Python 官方定義的，而是 Sphinx 的 reStructuredText (reST) 格式(筆者使用的 PyCharm 開發工具預設使用的)
其他還有 Epydoc, Numpydoc 和 Google 自己的格式等，筆者覺得使用編輯器預設或是團隊在使用的即可。

另外也可以使用 help 函式查詢，會顯示自訂的文件註解(Docstring)：

    
print(help(get_user_data_from_json))
    

輸出範例：

    
Help on function get_user_data_from_json in module __main__:

get_user_data_from_json(json_data: str) -> __main__.User
    從傳入的 json 中取得 使用者資料
    :param json_data: json 格式的使用者資料
    :return: 使用者資料

    

參考資料：
PEP 8 – Style Guide for Python Code
PEP 257 – Docstring Conventions
Stack OverFlow - Python: using 4 spaces for indentation. Why? [closed]
Stack OverFlow - pycharm """:return:""" in a Python documentation string
Stack OverFlow - What are the most common Python docstring formats? [closed]
Pycharm - Create documentation comments
GitHub Gist - nipunsadvilkar/Different_style_guide_python.md
Sphinx reStructuredText
Wiki - Epydoc