程式碼的註解

5.1 怎麼寫註解

在Python裡，就像很多程式語言一樣，你可以在程式碼中寫註解。註解幫助程式設計師和其他項目參與者理解代碼，這在協作和長期支持上特別有用。在Python中，有幾種方法可以在代碼中添加註解。

單行註解:

以#符號開頭。#後面的內容在同一行中會被Python忽略。這種類型的註解通常用於對某一行代碼的簡短說明或解釋。例如：

# 這是一個單行註解
print("Hello, World!") # 對函數操作的說明

多行註解:

在Python中沒有專門的多行註解語法，但可以通過多個單行註解或使用三引號來實現，雖然後者其實是多行字符串常量，不會被當作代碼執行。例如：

# 這是一個多行註解的例子 # 每行都以#號開頭
      

或：

""" 這是一個多行字串，用作註解。 Python把它解釋為一個字串，但如果它沒有賦值給變數或用於表達式中，就不會對這個字串做任何事情。 """ 
      

5.2 為什麼要寫註解

在代碼中使用註解可以提高可讀性，簡化維護和更新，並促進更有效的團隊協作。註解應該簡短但具信息性和相關性，以便作為有用的代碼文檔，而不會用多餘的信息污染它。

文檔字串 (docstrings):

通常位於模組、類、方法和函數的開頭以描述其用途。它們用三個雙引號括起來，可以用於自動生成文檔。

例子：

def add(a, b):
""" 加兩個數字的函數。 :param a: 第一個加數 :param b: 第二個加數 :return: a和b的和 """
    return a + b

在程式設計的世界裡，有時候開發者會在代碼中添加一些不僅能解釋，還能讓人會心一笑的註解。這裡有幾個有趣的代碼註解可以遇到：

例子1

 

            # 我可以解釋這裡發生了什麼，但連我自己都不清楚。
        

例子2

 

    # 如果這不工作，那是別人的錯。

例子3

 

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

例子4

 

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

這些註解可以為開發過程增添輕鬆和幽默，使得代碼庫不那麼單調。它們也提醒我們，軟件開發是一個創造性和人性化的過程。

5.3 快速註解代碼

在PyCharm中，你可以使用快捷鍵快速註解或取消註解代碼。為此，選擇你想要改變的代碼行，然後按下Windows上的Ctrl + /（或macOS上的Cmd + /）。這個鍵組合會在每一行前加上或去掉註解符號，讓過程變得快捷高效。