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!")

如你所見，你也可以使用註釋來臨時刪除程式碼段，例如第二個 print 語句。

註釋指南

以下指南來自 PEP 8，由 Guido van Rossum 編寫。

通用
- 與程式碼相矛盾的註釋比沒有註釋更糟糕。當代碼發生變化時，始終優先考慮保持註釋的最新狀態！
- 註釋應該使用完整的句子。如果註釋是短語或句子，它的第一個單詞應該大寫，除非它是一個以小寫字母開頭的識別符號（永遠不要更改識別符號的大小寫！）。
- 如果註釋很短，可以省略句末的句號。塊註釋通常由一個或多個由完整句子組成的段落組成，並且每個句子都應該以句號結尾。
- 句末句號後應該使用兩個空格。
- 在用英語寫作時，Strunk and White 的規則適用。
- 來自非英語國家的 Python 程式設計師：請用英語寫註釋，除非你 120% 確定程式碼永遠不會被不講你語言的人閱讀。
行內註釋
- 行內註釋是指與語句在同一行的註釋。行內註釋應該與語句之間至少隔開兩個空格。它們應該以 # 和一個空格開頭。
- 如果行內註釋陳述的是顯而易見的事實，它們是多餘的，事實上也會分散注意力。不要這樣做
```
x = x + 1  # Increment x
```
  但有時，這樣做是有用的
```
x = x + 1  # Compensate for border
```

文件字串

但如果你只是想知道如何使用函式、類或方法怎麼辦？你可以在函式前面添加註釋，但是註釋是在程式碼內部的，所以你必須開啟一個文字編輯器，並以這種方式檢視它們。但是你無法從 C 擴充套件中提取註釋，所以這不太理想。你始終可以編寫一個單獨的文字檔案來描述如何呼叫函式，但這意味著你必須記住更新該檔案。如果有一種機制可以讓你嵌入文件並輕鬆訪問它，那該多好啊……

幸運的是，Python 具有這樣的功能。文件字串（或 docstring）用於建立易於訪問的文件。你可以透過將字串作為第一個縮排語句新增到函式、類或模組中來新增 docstring。例如

#!/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 來獲取有關該模組的文件。

前一節: 錯誤

索引

下一節: 習語