軟體工程筆記 | 文件註解與類型提示：提升Python程式碼的可讀性與可維護性

前言

• 註釋
• 類型提示
• 文檔字串

寫註釋心法

• 解釋複雜的部分：如果你的代碼包含了複雜的算法或者技巧，你應該加註釋來解釋。
• 描述大的代碼塊：如果一段代碼完成了一個特定的任務，應該在其開始處添加註釋，描述它的功能和作用。
• 使用標準格式：許多程式語言都有標準的註釋格式，例如Java的Javadoc和Python的docstring。使用這些標準格式可以使得你的註釋更容易理解和使用。
• 避免過度註釋：不必對每一行代碼都寫註釋。如果代碼清晰易讀，則無需再添加註釋。(理論上是希望寫的都可讀性很好不需要註釋啦，但包含較複雜業務邏輯是無可必免）
• 寫註釋時思考閱讀者怎麼讀(換位思考)：當你寫註釋時，試著想像讀者的角度。他們可能不熟悉你的代碼，所以確保你的註釋足夠清晰和完整。

• 明確：註釋應該清楚地解釋代碼的目的。如果代碼的功能或行為不清楚，註釋應該提供解釋。
• 簡潔：註釋不應該冗長。如果可以用更少的文字表達相同的概念，那就應該這樣做。
• 準確：註釋應該準確地描述代碼的行為。如果代碼的行為改變了，註釋也應該隨之更新。
• 必要：不是所有的代碼都需要註釋。如果代碼已經足夠清晰，那麼添加註釋可能只會變得更加混亂。

註釋

舉例一

# 用戶輸入一個數字，該函數將回傳該數字的平方
def square(number):
    return number * number

# 計算平方
def square(number):
    return number * number

舉例二 (複雜版)

def fibonacci(n):
    """
    計算並返回斐波那契數列的第n個數字。
    
    Parameters:
    n (int): 需要計算的斐波那契數列元素的數量
    
    Returns:
    int: 斐波那契數列的第n個元素
    """
        
    # 遞迴調用函數本身，直到n為0或1
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        # n 大於1時，計算前兩個元素的和
        return fibonacci(n-1) + fibonacci(n-2)


def sum_fibonacci(n):
    """
    計算並Returns斐波那契數列的前n個數字之和。
    
    Parameters:
    n (int): 需要計算的斐波那契數列元素的數量
    
    Returns:
    int: 斐波那契數列的前n個元素之和
    """
    total = 0
    for i in range(n):
        # 累加從第一個元素到第n個元素的值
        total += fibonacci(i)
    return total

類型提示

from typing import List, Tuple

def calculate_sum_and_product(numbers: List[int]) -> Tuple[int, int]:
    """
    計算一個整數列表的總和和乘積。
    
    Parameters:
    numbers (List[int]): 一個整數列表
    
    Returns:
    Tuple[int, int]: 包含總和和乘積的元組
    """
    sum_of_numbers = sum(numbers)
    product_of_numbers = 1
    for num in numbers:
        product_of_numbers *= num
        
    return sum_of_numbers, product_of_numbers

文檔字串

結論