python 的 def 註解應該寫在哪邊?

 

 



在 Python 中，函式（def）的註解通常使用Docstring（文件字串）來撰寫，應該放在函式定義的第一行，使用三重引號（""" 或 '''）包圍。

範例

def add(a: int, b: int) -> int:
    """回傳兩數相加的結果。
    
    參數:
        a (int): 第一個數字
        b (int): 第二個數字
    
    回傳:
        int: 相加後的結果
    """
    return a + b


註解的最佳實踐
放在函式的第一行（函式內的縮排範圍）。
清楚描述函式的用途。
說明參數與回傳值（可選）。
可以使用 Google、NumPy 或 Sphinx 風格，但要保持一致。
其他風格範例
Google 風格 
def multiply(a: int, b: int) -> int:
    """計算兩數相乘的結果。

    Args:
        a (int): 第一個數字
        b (int): 第二個數字

    Returns:
        int: 相乘後的結果
    """
    return a * b


NumPy 風格

def divide(a: int, b: int) -> float:
    """計算兩數相除的結果。

    Parameters
    ----------
    a : int
        被除數
    b : int
        除數

    Returns
    -------
    float
        除法結果
    """
    return a / b

這樣的註解方式可以讓程式碼更易讀，並且可以透過 help(函式名稱) 查詢函式的用途。例如：

help(add)


這將會顯示 add 函式的 Docstring。