Python 中最常見的 Docstring 模式
記錄程式碼是一個好習慣，有抱負的開發人員和程式設計師應該養成在編碼之旅的早期階段記錄程式碼的習慣。
記錄原始碼可以提高原始碼的可讀性和管理能力，並使原始碼的新貢獻者非常容易理解它。
文件字串是寫在原始碼中的字串文字。它們充當程式碼片段的註釋或文件。文件字串用於描述類、函式，有時甚至是檔案。
換句話說，文件字串充當有關程式碼片段的後設資料。一個文件字串包含所有關於它們所描述內容的相關資訊。對於一個類，它包含以下資訊：
- 班上
- 類函式
- 類屬性。
對於函式，它包含有關以下內容的詳細資訊：
- 引數
- 引數的資料型別
- 引數的預設值
- 關於引數的簡短描述
- 函式返回什麼
- 函式返回的資料型別
- 函式引發的錯誤和異常以及有關的簡短描述
專業的 Python 開發人員使用幾種文件字串模式來記錄他們的程式碼。
可以建立他們的文件字串模式，而不是使用現有的。不過，這個決定完全取決於個人開發人員或開發人員團隊。
本文將討論 Python 程式語言的最佳文件字串模式。
Python 中的文件字串模式
以下是 Python 專業人士在行業中常用的一些最佳文件字串模式。
Epytext 模式
Epytext 模式是一種類似於 JavaDoc 的文件字串模式。它是 Epydoc 工具的一部分，用於使用其文件字串為 Python 模組生成文件。以下是 Epytext 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""
頂部提供了該功能的簡要說明。
所有函式引數都使用 @param 關鍵字編寫。函式返回內容的解釋寫在 @return 關鍵字旁邊。
如果函式引發錯誤或異常，則使用 @raise 關鍵字編寫它們。
休息模式
reSt 或 reStructuredText 是 Sphinx 使用的一種文件字串模式，Sphinx 是一種用於為 Python 程式語言生成文件的工具。此模式是 IT 行業中最常用的文件字串模式之一。
該方法還用作 Pyment 中的輸出格式，這是一種幫助 Python 程式設計師使用文件字串編寫增強程式碼文件的工具。當程式碼部分記錄或不包含文件字串時，此工具很有用。
JetBrains PyCharm IDE 或整合開發環境也使用 reST 模式。以下是 reST 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""
與 Epytext 模式類似，除了在 Epytext 模式中使用冒號或 : 作為關鍵字的字首而不是 at 符號或 @ 之外，此模式的所有內容都相同。
該方法的簡明或全面描述位於頂部。所有引數都位於 :param 關鍵字旁邊。該方法返回的內容的解釋寫在 :return 關鍵字旁邊。
並且，所有錯誤的詳細資訊都放在 :raise 關鍵字旁邊。
谷歌模式
列表中的另一個模式是 Google 模式。從技術上講，它的名字不是谷歌的模式，而是谷歌開發的模式。
這是一種在標題下組織細節的簡潔模式。Sphinx 工具也能夠識別這種模式並生成文件。
這種模式也是最多的文件字串模式之一。以下是 Google 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Args:
parameter1: this is the first parameter.
parameter2: this is the second parameter.
Returns:
this is a description of what is returned by the function.
Raises:
KeyError: raises an exception.
TypeError: raises an exception.
"""
與前面的模式一樣，該方法的簡潔描述位於頂部。
描述之後是諸如 Args、Returns 和 Raises 之類的標題。在 Args 標題下，放置了所有引數和詳細資訊，例如它們的型別和預設值。
函式返回內容的描述放在 Returns 標題下。最後，錯誤或異常及其詳細資訊寫在 Raises 標題下。
Numpydoc 模式
numpy 模組具有稱為 Numpydoc 模式的文件字串模式。
該模式類似於 Google 模式，可以被 Sphinx 工具識別。與 Google 模式類似，資訊按標題組織。
以下是 Numpydoc 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Parameters
----------
parameter1 : int
this is the first parameter.
parameter2 : str, "default value"
this is the second parameter.
Returns
-------
string
returns a string value.
Raises
------
KeyError
raises an exception.
TypeError
raises an exception.
"""
方法的描述寫在頂部。有關該方法的其他詳細資訊在標題下組織：Parameters、Returns 和 Raises。
有關引數的所有詳細資訊，包括它們的預設值、值型別等，都放在 Parameters 標題下。關於函式返回內容的所有詳細資訊，包括資料型別，都位於 Returns 標題下。
最後，關於錯誤或異常的資訊和一些描述寫在 Raises 標題下。
