Python/源文件和註釋

文檔是留下有關代碼的信息的過程。在 Python 中,執行此操作的兩種機制是註釋和文檔字符串。

註釋

編輯

總會有需要返回代碼的時候。也許是為了修復錯誤,或者添加新功能。無論如何,六個月後再查看自己的代碼幾乎和查看別人的代碼一樣糟糕。我們需要的是一種提醒自己當時做了什麼的方法。

為此,您可以留下註釋。註釋是嵌入在代碼中的小段文本,Python 解釋器會忽略這些文本。註釋用井號 (#) 表示,並延伸到行尾。例如:

#!/usr/bin/env python
# commentexample.py

# Display the knights that come after Scene 24
print("The Knights Who Say Ni!")
# print("I will never see the light of day!")

如您所見,您還可以使用註釋暫時刪除代碼段,例如第二條打印語句。

註釋指南

編輯

以下準則來自 PEP 8,由 Guido van Rossum 編寫。

  • 常規
    • 與代碼相矛盾的註釋比沒有註釋更糟糕。始終優先考慮在代碼更改時保持註釋的更新!
    • 註釋應為完整的句子。如果註釋是短語或句子,則其第一個單詞應大寫,除非它是以小寫字母開頭的標識符(切勿改變標識符的大小寫!)。
    • 如果註釋很短,則可以省略末尾的句號。塊註釋通常由一個或多個由完整句子構成的段落組成,每個句子都應以句號結尾。
    • 句末句號後應使用兩個空格。
    • 撰寫英語時,適用 Strunk and White
    • 來自非英語國家的 Python 程式設計師:請用英語撰寫註釋,除非您 120% 確定代碼不會被不講您語言的人閱讀。
  • 內聯註釋
    • 內聯註釋是與語句在同一行的註釋。內聯註釋應與語句至少相隔兩個空格。它們應以 # 和一個空格開頭。
    • 內聯註釋沒有必要,如果陳述顯而易見的內容,實際上會分散注意力。不要這樣做:
      x = x + 1 # 增加 x
      
      但有時,這很有用:
      x = x + 1 # 补偿边框
      

文檔字符串

編輯

但是,如果您只是想知道如何使用函數、類或方法,該怎麼辦?您可以在函數前添加註釋,但註釋在代碼內部,因此您必須打開文本編輯器並以這種方式查看它們。但是您無法從 C 擴展中調出註釋,因此這並不理想。您可以隨時編寫一個單獨的文本文件來說明如何調用函數,但這意味着您必須記住更新該文件。如果只有一種機制能夠嵌入文檔並輕鬆獲取它...

幸運的是,Python 具有這樣的功能。文檔字符串(或 docstrings)用於創建易於訪問的文檔。您可以通過添加字符串作為第一個縮進語句來向函數、類或模塊添加 docstrings。例如:

#!/usr/bin/env python
# docstringexample.py

"""Example of using documentation strings."""

class Knight:
    """
    An example class.
    
    Call spam to get bacon.
    """
    
    def spam(eggs="bacon"):
        """Prints the argument given."""
        print(eggs)

慣例是使用三引號字符串,因為這樣可以更輕鬆地添加跨多行的更多文檔。

要訪問文檔,您可以在 Python shell 中使用 help 函數來獲取需要幫助的對象,也可以使用系統 shell 中的 pydoc 命令。如果我們在 docstringexample.py 所在的目錄中,則可以輸入 pydoc docstringexample 來獲取該模塊的文檔。