軟體工程筆記 | 文件註解與類型提示：提升Python程式碼的可讀性與可維護性
本文靈感來自：How to Document Your Code Like a Pro
以下範例程式均為 Python
推薦插件:better comment
前言
程式碼的有效文件化是編程最重要的部分之一
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
註釋應該用來解釋程式碼的功能和目的，並澄清可能存在的任何模糊或複雜的部分。如果註釋只是重複程式碼本身的內容，那麼它就沒有發揮其應有的作用。
類型提示
(這個算是 Python 獨有的，因為 Python 是動態語言不需要類型提示，但是如果有類型提示，可以讓程式碼更好閱讀，我自己是都會加上類型提示)
類型提示是Python 3.5之後引入的特性，它們提供了一種明確指定變量和函數Returns值類型的方式。這不僅使得程式碼更清晰，而且還可以幫助防止錯誤的發生。例如，在執行銀行轉帳操作時，將金額明確定義為整數可以避免混淆和可能的錯誤。
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
在這個例子中，calculate_sum_and_product函數有一個Parametersnumbers，它的類型被註明為List[int]，表示它應該是一個整數列表。此函數的Returns類型被註明為Tuple[int, int]，表示它將Returns一個包含兩個整數的元組。
這樣的類型提示讓我們在編寫或閱讀程式碼時就能了解每個函數的輸入和輸出類型，這對於理解程式碼的運作方式，以及避免因類型錯誤導致的bug非常有幫助。
文檔字串
以上舉例中在 """ """ 之間的文字就是 docstrings
文檔字串是對函數、方法、類和模組進行詳細說明的工具。使用文檔字串，開發者可以生成詳細的文檔網站，方便其他開發者或使用者查閱。VS Code的Auto Docstring擴展和GitHub Copilot等工具可以自動生成文檔字串，節省開發者的時間和精力。然而，需要注意的是，這些工具可能會生成過多的文檔，導致程式碼變得冗長。
文檔字串也能幫助生成文件，可以透過 “mkdocstrings” 來直接使用 Python 的 docstrings 生成文檔。該插件能夠自動解析你的 Python 程式碼中的 docstrings，然後將其轉換為 MkDocs 格式。
結論
編寫清晰、組織良好的程式碼是比寫大量的註釋和文檔更有效的方式。
良好的命名和組織可以使你的程式碼更易於理解，並減少需要大量文件化的需要。
因此，我們應將焦點放在編寫高質量的程式碼，而不僅僅是文件化。
# 用戶輸入一個數字，該函數將回傳該數字的平方
def square(number):
return number * number# 計算平方
def square(number):
return number * numberdef 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 註釋應該用來解釋程式碼的功能和目的，並澄清可能存在的任何模糊或複雜的部分。如果註釋只是重複程式碼本身的內容，那麼它就沒有發揮其應有的作用。
類型提示
(這個算是 Python 獨有的，因為 Python 是動態語言不需要類型提示，但是如果有類型提示，可以讓程式碼更好閱讀，我自己是都會加上類型提示)
類型提示是Python 3.5之後引入的特性，它們提供了一種明確指定變量和函數Returns值類型的方式。這不僅使得程式碼更清晰，而且還可以幫助防止錯誤的發生。例如，在執行銀行轉帳操作時，將金額明確定義為整數可以避免混淆和可能的錯誤。
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 在這個例子中，calculate_sum_and_product函數有一個Parametersnumbers，它的類型被註明為List[int]，表示它應該是一個整數列表。此函數的Returns類型被註明為Tuple[int, int]，表示它將Returns一個包含兩個整數的元組。
這樣的類型提示讓我們在編寫或閱讀程式碼時就能了解每個函數的輸入和輸出類型，這對於理解程式碼的運作方式，以及避免因類型錯誤導致的bug非常有幫助。
文檔字串
以上舉例中在 """ """ 之間的文字就是 docstrings
文檔字串是對函數、方法、類和模組進行詳細說明的工具。使用文檔字串，開發者可以生成詳細的文檔網站，方便其他開發者或使用者查閱。VS Code的Auto Docstring擴展和GitHub Copilot等工具可以自動生成文檔字串，節省開發者的時間和精力。然而，需要注意的是，這些工具可能會生成過多的文檔，導致程式碼變得冗長。
文檔字串也能幫助生成文件，可以透過 “mkdocstrings” 來直接使用 Python 的 docstrings 生成文檔。該插件能夠自動解析你的 Python 程式碼中的 docstrings，然後將其轉換為 MkDocs 格式。
結論
編寫清晰、組織良好的程式碼是比寫大量的註釋和文檔更有效的方式。
良好的命名和組織可以使你的程式碼更易於理解，並減少需要大量文件化的需要。
因此，我們應將焦點放在編寫高質量的程式碼，而不僅僅是文件化。
分享至
成為作者繼續創作的動力吧！
