許多程式語言官方並沒有要求要用兩個空格還是四個空格、程式碼中間有幾行空白等等,不過在 Python 中有列出詳細的官方建議,包含註解也是。
在 # 號和內容中間要有一個空格。
在 Python 官方的程式碼風格指南 中有提到一行程式碼中最多為 79 個字元,對於字串和註解則是 72 個字元(characters)。並且也有提到如果喜歡較長程式碼的團隊也可以將限制增加到 99 個字元,但是字串和註解還是 72 個字元。
並且官方也建議註解應該是完整的句子,首字母大寫,除非是以小寫開頭的特殊字母。並且非英語國家的軟體工程師也要使用英文寫註解,除非你 120% 確定程式碼不會有不講此語言的人閱讀。
註: 上面有提到官方建議註解要使用英文,在本文的範例中為了方便說明會使用中文註解
如果是與程式碼同一行的註解稱為行內註解(Inline Comments),官方要求註解和程式碼要空兩格,並且盡量少用。
在許多 IDE 中都可以快速查看註解,下圖是筆者常用的開發工具 PyCharm 的顯示範例:
如果有多行可以看下面的範例:
在上面可以看到 :return: 這樣特殊的文字,並且在顯示中會有特殊的顯示方式,不過這個並不是 Python 官方定義的,而是 Sphinx 的 reStructuredText (reST) 格式(筆者使用的 PyCharm 開發工具預設使用的)
其他還有 Epydoc, Numpydoc 和 Google 自己的格式等,筆者覺得使用編輯器預設或是團隊在使用的即可。
另外也可以使用 help 函式查詢,會顯示自訂的文件註解(Docstring):
輸出範例:
參考資料:
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
單行註解
# 這是一個註解
在 # 號和內容中間要有一個空格。
在 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
留言
張貼留言
如果有任何問題、建議、想說的話或文章題目推薦,都歡迎留言或來信: a@ruyut.com