Python 中的註解

1. 如何撰寫註解

在 Python 中，像許多其他程式語言一樣，可以在程式碼中撰寫註解。

註解就是給其他程式員看的文字： Python 解譯器不會對註解做出任何回應，也不會執行其中的程式碼。註解幫助程式員和專案中的其他成員理解程式碼，這在合作開發和長期維護程式時非常有用。在 Python 中有幾種方式可以在程式碼中新增註解。

單行註解:

以符號 # 開頭。在 # 之後的同一行的內容，Python 解譯器會忽略掉。這種類型的註解通常用於簡短的說明或解釋某行程式碼。範例：

# 這是一個單行註解
print("Hello, World!")  # 功能動作的說明

多行註解:

Python 中並沒有官方的多行註解語法，但可以用多個單行註解實現，或者使用三重引號，不過後者實際上是一個多行的字串型別文字常數，並不會被執行為程式碼。範例：

# 這是一個多行註解的範例
# 每行都以符號 `#` 開始

或者:

"""
這是一個多行的字串，可以被用作註解。
Python 將其解釋為字串，但如果未賦值給變數或未在表達式中使用，它不會執行任何操作。
"""

有用的小知識! 字串型別文字常數（Literal）是在程式碼中直接記錄的少量資料：例如數字、字串等。

2. 為什麼要撰寫註解

在程式碼中使用註解能提高程式碼的可讀性，方便維護和更新，並促進團隊間更有效的合作。註解應該簡潔明瞭，能提供有用的程式文件資訊，而不應包含過多無關的資料。

文件字串 (docstrings):

這是一種多行字串，通常位於模組、類別、方法和函數的開頭，用於描述它們的用途。這些字串使用三對雙引號進行包裹，並用於自動生成文件。

範例:

def add(a, b):
    """
    用於兩數相加的函數。
    :param a: 第一個加數
    :param b: 第二個加數
    :return: a 與 b 的總和
    """
    return a + b

在程式開發世界裡，開發者有時會在程式碼中加入註解，這些註解不僅用於解釋，還能帶來一點幽默感。以下是一些在程式碼中可能見到的有趣註解：

範例 1:

# 我本來想解釋這裡發生了什麼，但現在連我自己也搞不懂了。

範例 2:

# 如果這段程式碼無法運行，那肯定是別人的錯。

範例 3:

# 來了，看見，修好了... 然後壞了。

範例 4:

# 當我寫這個時候，只有我和上帝知道它是怎麼運作的。
# 現在只有上帝知道。

範例 5:

# 在這裡浪費的時間總數 = 42 小時。

這些註解可以為開發過程添加一些輕鬆和幽默的氣氛，讓程式碼基礎更有趣，也提醒我們，軟件開發是創造性與人性化的過程。

5.3 快速註解程式碼

在 PyCharm IDE 中，你可以使用快捷鍵快速註解或取消註解程式碼。為此，選擇要註解或取消註解的程式碼行，然後按下 Ctrl + / 在 Windows 中（或 Cmd + / 在 macOS 中）。此按鍵組合會在所選行中新增或移除註解符號，使這個過程快速且高效。