5.2 函數書寫規范

5.2.1 文檔字符串

良好的代碼書寫規范不僅便于他人閱讀，更是一個開發人員應有的素養。由于函數往往用于實現一系列復雜的邏輯運算，所以在編寫函數時更應該注意代碼規范，使函數調用者能夠準確理解函數的使用方法，圖5-1是Python內置的print函數的注釋。

圖5-1

從截圖中可以知道，print函數的作用是將一些值打印到一個流對象或者系統的標準輸出設備。同時還提供了幾個可選參數進行復雜的打印操作。

自定義的函數也應提供合適的函數注釋，幫助使用者理解函數。

在Python中使用文檔字符串（DocString）可以提供對函數功能的說明，文檔字符串存儲在__doc__中。文檔字符串必須出現在模塊、方法、類或者函數內部的第一行。Python官方推薦所有的模塊以及模塊內部的類與方法都應該有文檔字符串，另外類的所有公共方法如構造函數（__init__）也應該提供文檔字符串。

Python推薦使用三個雙引號將文檔字符串括起來，如"""Add two numbers."""。如果在文檔字符串中出現了反斜杠（/），則需要在文檔字符串前添加小寫字母r，如r"""It\'s a function to get the summary of two numbers."""。如果文檔字符串中出現了unicode字符，則需要在字符串前添加一個小寫字母u，例如：u"""計算兩數之和。"""。

單行文檔字符串的書寫有以下注意事項：

□ 即使文檔只有一行，也要使用三引號將字符串括起來。

□ 如果文檔只有一行，那么三引號開頭與結尾也要在一行。

□ 在文檔字符串中不能出現任何空白行。

□ 文檔字符串用來描述方法或函數的作用，而不能有其他描述性的文字。

□ 文檔字符串中不要重復出現函數的簽名，如"""function(a,b)->list"""。

多行文檔字符串的書寫有以下注意事項：

□ 第一行類似于單行文檔字符串，用于表達總結性的信息，其后緊跟一個空行，最后是更詳細的描述性信息。

□ 總結性的信息必須緊跟在開始三引號之后。

□ 詳細的描述信息的縮進應該與三引號一致。

一個包含多行文檔字符串的示例如下：

此時在Visual Studio Code中調用上面complex方法時也會給出提示信息，如圖5-2所示。

圖5-2

5.2.2 函數注釋

除了文檔字符串外，在Python 3中還提供了一個新功能：函數注釋。函數注釋完全是一個可選的功能，它以字典的形式存儲在__annotations__中，不會對函數本身造成任何影響。

函數注釋的使用方法為：

    def 函數名(參數名："參數注釋"="默認值", …) -> "函數返回值注釋":
        函數體

例：修改add方法，添加相應的函數注釋：

    def add(x:"Number 1"=0, y:"Number 2"=0) -> int:
        """Add two numbers."""
    return x + y

調用add方法：

        >>> print(add.__annotations__)
    >>> sum = add()
    >>> print(sum)

輸出：

    {'x': 'Number 1', 'y': 'Number 2', 'return': <class 'int'>}
    0

由此可見，函數參數、返回值的說明信息都被保存在屬性__annotations__中，方便用戶了解并使用函數。