Python docstring（檔案字串）：給程式碼新增註釋

dcostring 是一種特殊型別的注釋，可以把它放在一個函數或類定義之後，或者一個檔案的開頭，其功能是說明函數、類或者模組是做什麼的。

docstring 可以用三個引號、單引號或者雙引號括起來，如下所示：

class Test:
    '''測試 docstring 的類
    '''
    def __init__(self):
        '''Test類初始化物件,不需要任何引數
        '''
        self.num = 10
t = Test()
help(t)

有讀者可能會問，為什麼不直接使用注釋？因為 docstring 在 Python 中很特殊，有一些 Python 內建的函數，可以使用 docstring 來幫助其他程式設計師來使用你的程式碼。

執行上面程式，可以看到如下輸出結果：

Help on Test in module __main__ object:

class Test(builtins.object)
|  測試 docstring 的類
| 
|  Methods defined here:
| 
|  __init__(self)
|      Test類初始化物件,不需要任何引數
| 
|  ----------------------------------------------------------------------
|  Data descriptors defined here:
| 
|  __dict__
|      dictionary for instance variables (if defined)
| 
|  __weakref__
|      list of weak references to the object (if defined)

可以看到，help() 函數找到了所有的函數和 docstring，並且自動建立了一個格式漂亮的幫助頁面。由此，使用者不需要深入你的程式碼，就可以知道哪些函數可用，函數需要接受什麼引數。

這裡給初學者總結了適合寫在 docstring 中的內容：

• 函數或者類、模板是乾什麼的；
• 對於類來說，它是否可以直接使用，或者它只是基礎類別，不能單獨使用；
• 使用者期望從一個函數中返回什麼；
• 在使用過程中，可能會給出的警告型別；
• 如果包含引數，則引數的值應該是什麼資料型別。

注意，PEP 257 中包含了編寫 docstring 的指南，感興趣的讀者可前往 Python PEP-0257 進行閱讀。