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 來獲取該模塊的文檔。