Python - 註解：初學者指南

你好啊，未來的 Python 大師們！今天，我們將深入探討一個可能看似微不足道但在編程世界中卻非常重要的主題：註解。作為你友善的鄰居電腦老師，我來引導你了解 Python 註解的來龍去脈。所以，拿起你的虛擬筆記本，我們開始吧！

Python - Comments

什麼是 Python 註解？

在我們深入細節之前，讓我們先了解註解是什麼。想像你正在為未來的自己寫一份食譜。你可能會添加像 "媽媽的秘密配方" 或 "攪拌到它看起來像銀河漩渦" 這樣的小筆記。那正是編程中的註解 - 我們留給自己和其他人理解我們代碼的小筆記。

在 Python 中，註解是在運行你的代碼時 Python 解譯器完全忽略的文本行。它們只存在於人眼！

Python 中的單行註解

讓我們從最簡單的註解形式開始：單行註解。

基本知識

在 Python 中，你可以使用井號（#）創建單行註解。那行中的 # 之後的任何東西都被視為註解。

# 這是一個單行註解
print("Hello, World!")  # 這也是一個註解，但是在一些代碼之後

在這個例子中，第一行完全是註解。第二行有代碼後跟註解。 Python 只會執行 print("Hello, World!") 部分。

實際示例

讓我們看一下更實用的例子：

# 計算矩形的面積
length = 10  # 長度（以米为单位）
width = 5    # 寬度（以米为单位）
area = length * width  # 公式：面積 = 長度 * 寬度
print(f"矩形的面積是 {area} 平方米")

在這裡，我們使用註解來解釋每行的作用。這對於學習或當你的代碼變得更複雜時特別有用。

專業建議

我總是告訴我的學生："註解要像讀你代碼的人是個知道你住哪裡的暴力精神病一樣。" 這有點戲劇化，但這個觀點表達了一個意思 - 清晰的註解可以為你（或其他人）節省許多頭痛！

Python 中的多行註解

現在，如果你想寫一個跨越多行的註解呢？ Python 沒有特定的多行註解語法，但我們有個巧妙的方法。

使用三重引號

我們可以使用三重引號（''' 或 """）創建多行字符串，這些字符串可以有效地用作多行註解：

'''
這是一個多行註解。
它可以跨多行。
Python 在執行時會忽略它。
'''

"""
這是另一種使用
雙引號編寫
多行註解的方法。
"""

print("代碼在這裡繼續")

這兩種方法都創建了未賦值給任何變量的字符串，因此 Python 會有效地忽略它們。這是一個小騙局，但效果非常好！

何時使用多行註解

多行註解適用於以下情況：

解釋複雜的算法
提供函數或類的概述
暫時禁用大量代碼（但對此要小心！）

以下是一個更詳細的例子：

def calculate_fibonacci(n):
"""
這個函數計算斐波那契序列中的第 n 個數字。

斐波那契序列定義為：
F(n) = F(n-1) + F(n-2)，其中 F(0) = 0 和 F(1) = 1

參數：
n (int): 要計算的斐波那契序列中的位置

返回：
int: 第 n 個斐波那契數
"""
if n <= 1:
return n
else:
return calculate_fibonacci(n-1) + calculate_fibonacci(n-2)

# 示例使用
print(calculate_fibonacci(10))

在這個例子中，我們使用一個多行註解（在 Python 中稱為 docstring）來解釋函數的作用、工作原理以及它期望的參數。這對於文檔目的非常有幫助。

使用註解進行文檔化

註解不僅用於解釋你的代碼；它們也對文檔至關重要。好的文檔可以讓一個好的編程師變得更好！

Docstrings

我們已經在上面看到了一個 docstring 的例子。在 Python 中，函數、類或模塊定義之後的第一個字符串稱為 docstring。這是一種特殊的註解，可以通過程序訪問。

def greet(name):
"""
這個函數對作為參數傳遞的人表示問候。

參數：
name (str): 要問候的人的名字

返回：
str: 一個問候信息
"""
return f"你好，{name}！你今天怎麼樣？"

# 你可以像這樣訪問 docstring:
print(greet.__doc__)

行內註解

有時，一個快速的行內註解可以挽救一整天：

result = x * 5 + y / 2 - z  # 使用第 42 頁的特殊公式

這種註解在處理複雜的計算或算法時可能非常有價值。

使用註解的最佳實踐

讓我們結束一些使用註解的黃金法則：

法則	描述	示例
要清晰	寫出解釋 '為什麼' 而不是 '什麼' 的註解	`# Increment i to avoid infinite loop`
保持更新	更改代碼時始終更新註解	`# Now using improved algorithm (v2.0)`
不要陳述明顯的事實	避免不增加價值的註解	❌ `x = x + 1 # Add 1 to x`
使用正確的語法	將註解當作任何其他寫的文本	`# 計算輸入值的平均值`
註解複雜的部分	專注於你的代碼的複雜部分	`# 當輸入為空時處理邊緣情況`

請記住，註解的目標是使你的代碼更容易理解。正如我的一個學生曾經說過的，"好的註解就像一個好笑話 - 如果你必須解釋它們，它們可能不太好！"

總之，掌握撰寫良好註解的藝術是任何程序員的重要技能。這不僅幫助其他人理解你的代碼，而且當你未來幾個月或幾年後回頭看你自己的代碼時，也會幫助你。開心註解，願你的代碼始終清晰易懂！

Credits: Image by storyset