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

更新於 發佈於 閱讀時間約 8 分鐘

本文靈感來自:How to Document Your Code Like a Pro
以下範例程式均為 Python
推薦插件:better comment


raw-image


前言

程式碼的有效文件化是編程最重要的部分之一
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 格式。

結論

編寫清晰、組織良好的程式碼是比寫大量的註釋和文檔更有效的方式。
良好的命名和組織可以使你的程式碼更易於理解,並減少需要大量文件化的需要。
因此,我們應將焦點放在編寫高質量的程式碼,而不僅僅是文件化。

留言
avatar-img
留言分享你的想法!
阿Han-avatar-img
2023/08/25
一個好的文檔顯示出開發者的水平
avatar-img
我人生遊戲的通關討論區
32會員
89內容數
對我來說 人生就是一個遊戲 活得開心,活得漂亮,活得成功,活得有意義 都是這場遊戲的一個個任務 我想要把這個遊戲打通關 在這裡我會分享一些我自己的經驗 把遊戲打通關的一些技巧 打通關的過程 和我自己發現的小 bug,或捷徑 遇到的喜怒哀樂 遇到的困難 遇到的挫折 歡迎大家一起來摸透和想受 這場人生遊戲
2023/08/05
在Python的typing模組中,NewType用來創建新的類型,其實是一個現有類型的變體。這對於型別檢查(Type Checking)非常有用,能夠幫助我們更清楚地理解我們的代碼和預期的行為。
Thumbnail
2023/08/05
在Python的typing模組中,NewType用來創建新的類型,其實是一個現有類型的變體。這對於型別檢查(Type Checking)非常有用,能夠幫助我們更清楚地理解我們的代碼和預期的行為。
Thumbnail
2023/08/03
方法鏈接和流暢接口在許多現代編程語言和框架中都有使用。這兩個概念有時互相重疊,因為流暢接口通常使用方法鏈接來實現。使用這些技巧可以提高程式碼的可讀性和維護性,使得編碼更符合人類語言的結構。這對於在專案中協同工作的團隊尤為重要,因為它可以讓每個人更容易理解和使用代碼。
Thumbnail
2023/08/03
方法鏈接和流暢接口在許多現代編程語言和框架中都有使用。這兩個概念有時互相重疊,因為流暢接口通常使用方法鏈接來實現。使用這些技巧可以提高程式碼的可讀性和維護性,使得編碼更符合人類語言的結構。這對於在專案中協同工作的團隊尤為重要,因為它可以讓每個人更容易理解和使用代碼。
Thumbnail
2023/06/11
在程式設計中,我們通常會遇到一個問題: 何時應該使用具有方法的類別,何時應該在模組中使用函式? 如果選擇不當,你的程式碼可能比需要的更複雜,這使得維護更困難 首先,我們需要更好地理解函式和類別的差異。 函式接收輸入參數,然後進行一些操作,並返回結果。你可以將這個結果傳遞給其他函式。在像Haskell
Thumbnail
2023/06/11
在程式設計中,我們通常會遇到一個問題: 何時應該使用具有方法的類別,何時應該在模組中使用函式? 如果選擇不當,你的程式碼可能比需要的更複雜,這使得維護更困難 首先,我們需要更好地理解函式和類別的差異。 函式接收輸入參數,然後進行一些操作,並返回結果。你可以將這個結果傳遞給其他函式。在像Haskell
Thumbnail
看更多
你可能也想看
Thumbnail
每年4月、5月都是最多稅要繳的月份,當然大部份的人都是有機會繳到「綜合所得稅」,只是相當相當多人還不知道,原來繳給政府的稅!可以透過一些有活動的銀行信用卡或電子支付來繳,從繳費中賺一點點小確幸!就是賺個1%~2%大家也是很開心的,因為你們把沒回饋變成有回饋,就是用卡的最高境界 所得稅線上申報
Thumbnail
每年4月、5月都是最多稅要繳的月份,當然大部份的人都是有機會繳到「綜合所得稅」,只是相當相當多人還不知道,原來繳給政府的稅!可以透過一些有活動的銀行信用卡或電子支付來繳,從繳費中賺一點點小確幸!就是賺個1%~2%大家也是很開心的,因為你們把沒回饋變成有回饋,就是用卡的最高境界 所得稅線上申報
Thumbnail
在Python中,我們可以用def關鍵字定義函數,並透過函數名稱呼叫它。函數參數可以是必填、關鍵字、默認或不定長度的類型。return語句負責結束函數並回傳值。全域變數可以在整個程序中使用,而區域變數只能在特定函數內使用。我們還可以在一個文件中定義函數,然後在另一個文件中呼叫它。
Thumbnail
在Python中,我們可以用def關鍵字定義函數,並透過函數名稱呼叫它。函數參數可以是必填、關鍵字、默認或不定長度的類型。return語句負責結束函數並回傳值。全域變數可以在整個程序中使用,而區域變數只能在特定函數內使用。我們還可以在一個文件中定義函數,然後在另一個文件中呼叫它。
Thumbnail
本文將介紹自定函式及應用,利用程式範例解釋為什麼要用到自定函式 自定函式好處當然就是,讓你的程式碼看起來比較簡潔,在重複使用到的程式碼區塊,可以包裝成函式,讓你重複使用它。
Thumbnail
本文將介紹自定函式及應用,利用程式範例解釋為什麼要用到自定函式 自定函式好處當然就是,讓你的程式碼看起來比較簡潔,在重複使用到的程式碼區塊,可以包裝成函式,讓你重複使用它。
Thumbnail
在軟體開發領域,乾淨程式碼是一個極為重要的概念。乾淨程式碼不僅僅是讓代碼運作正確,更是確保代碼易於閱讀、理解和維護的關鍵。本文將深入探討如何撰寫乾淨程式碼,並介紹一些提升代碼可讀性與維護性的最佳實踐方法。
Thumbnail
在軟體開發領域,乾淨程式碼是一個極為重要的概念。乾淨程式碼不僅僅是讓代碼運作正確,更是確保代碼易於閱讀、理解和維護的關鍵。本文將深入探討如何撰寫乾淨程式碼,並介紹一些提升代碼可讀性與維護性的最佳實踐方法。
Thumbnail
我們將探索函式的定義和調用,這是程式設計中非常重要且強大的概念,它可以將大型程式切割成小的、可重複使用的函式。讓我們一起來了解吧!函式的定義、呼叫和返回值是學習函式的核心。
Thumbnail
我們將探索函式的定義和調用,這是程式設計中非常重要且強大的概念,它可以將大型程式切割成小的、可重複使用的函式。讓我們一起來了解吧!函式的定義、呼叫和返回值是學習函式的核心。
Thumbnail
本文靈感來自:How to Document Your Code Like a Pro 以下範例程式均為 Python 推薦插件:better comment 前言 程式碼的有效文件化是編程最重要的部分之一 Python 提升可讀性有以下方式: 註釋 類型提示 文檔字串 這些實踐可以提高程式碼的可讀
Thumbnail
本文靈感來自:How to Document Your Code Like a Pro 以下範例程式均為 Python 推薦插件:better comment 前言 程式碼的有效文件化是編程最重要的部分之一 Python 提升可讀性有以下方式: 註釋 類型提示 文檔字串 這些實踐可以提高程式碼的可讀
Thumbnail
Python 基本語法 python 語法的後綴名是以.py 結尾 python 執行方式 使用交互介面執行 使用 python test.py 命令執行 使用./test.py 執行 python 標示符 以單下劃線開頭的屬性,表示是類的私有屬性(包括方法,變量)。如:_foo表示不能直接訪問的類
Thumbnail
Python 基本語法 python 語法的後綴名是以.py 結尾 python 執行方式 使用交互介面執行 使用 python test.py 命令執行 使用./test.py 執行 python 標示符 以單下劃線開頭的屬性,表示是類的私有屬性(包括方法,變量)。如:_foo表示不能直接訪問的類
Thumbnail
在看官網文件時,看到一份文件:PEP 8 -- Style Guide for Python Code。這份文件是關於Python程式碼風格的指引和建議。
Thumbnail
在看官網文件時,看到一份文件:PEP 8 -- Style Guide for Python Code。這份文件是關於Python程式碼風格的指引和建議。
追蹤感興趣的內容從 Google News 追蹤更多 vocus 的最新精選內容追蹤 Google News