如何在 Python 中發表評論——初學者快速指南

註釋是任何編程語言（包括 Python）的重要組成部分。它們幫助您和其他開發人員理解代碼的邏輯和功能。當您向 Python 代碼添加註釋時，它不僅可以幫助您解釋代碼，還可以增強代碼的可讀性、質量和可維護性。

在本 Python 教程中，我們將探討如何編寫單行註釋、多行註釋和多行字符串。我們將深入研究在 Python 程序中使用註釋的詳細概述，了解不同類型的 Python 註釋，以及每種註釋類型的各種用例。這將包括演示如何編寫好的註釋、添加內聯註釋以及避免編寫糟糕的代碼的示例。

讓我們開始吧。

目錄

• 什麼是單行註釋？
• 什麼是多行註釋？
  • 使用三重引號
  • 在行繼續中使用哈希符號
• 什麼是行內評論？
• 什麼是文檔字符串？
  • 函數和方法文檔字符串
  • 類文檔字符串
  • 模塊文檔字符串
• 撰寫評論的最佳實踐
  • 清晰簡潔
  • 避免明顯的評論
  • 在代碼更改時更新註釋
• 結論

什麼是單行註釋？

在Python編程中，單行註釋是在行首使用哈希字符 (#) 創建的。同一行上井號後面的任何文本都被視為單行註釋，Python 解釋器將不會執行它。

在 Python 代碼中使用單行註釋有兩個主要目的：

1. 提供特定 Python 代碼段的簡要說明或單行摘要，提供對代碼功能或目的的洞察。

2. 暫時禁止執行單行代碼，這在調試或測試期間很有幫助，而無需從腳本中永久刪除代碼。

下面舉例說明如何在一行中編寫註釋來解釋 Python 代碼：

在此示例中，每個單行註釋都對每個代碼行進行了解釋，使您和其他開發人員更容易理解代碼的用途。

下面的Python代碼演示瞭如何編寫註釋來防止單行代碼被執行：

在上面的示例中，用於調試目的的帶有字符串文字的控制台打印語句已被註釋掉，以防止其在代碼運行時執行。單行註釋確保Python解釋器將該行視為註釋，而不是一段代碼。

當您調試和解決錯誤時，註釋掉特定的代碼行會很有幫助。

養成編寫清晰、簡潔和相關的單行註釋的習慣是一種很好的做法，因為它有助於專注於解釋代碼的特定方面。通過編寫良好的註釋，您可以顯著增強 Python 程序的可讀性和可維護性，使其他人更容易理解和使用您的代碼。

什麼是多行註釋？

在提供有關特定代碼部分的更廣泛的解釋或註釋時，Python多行註釋很有用。當您需要在調試或開發期間暫時禁用多行代碼而不必單獨註釋掉每一行時，它們也會派上用場。

在 Python 中創建多行註釋有兩種方法：

1. 使用三引號

2. 繼續使用哈希符號

使用三重引號

在Python中創建多行註釋的一種方法是使用三重引號，它由三個連續的單引號或雙引號組成。

當一段文本包含在三重引號中時，Python 將其解釋為字符串，如果未分配給變量則忽略它。

此技術允許您編寫跨多行的 Python 多行註釋或多行字符串，從而增強代碼的可讀性。

以下代碼有助於解釋在 Python代碼中對多行註釋塊使用三重引號：

'''
This is a multi-line comment
in Python using triple quotes.
'''
print("Hello World!")

上面的代碼只會輸出“Hello World!” 因為解釋器忽略了三重引號的多行字符串。

在行繼續中使用哈希符號

在 Python 中創建多行註釋的另一種方法是在每行的開頭使用井號 (#)，並使用續行符 () 來保持可讀性。

下面是如何在 Python 中編寫多行註釋的示例：

# This is a multi-line comment in Python
# using hash symbols with line continuation.
# It spans multiple lines, but each line requires a hash symbol.
print("Hello World!")

在上面的例子中，只有“Hello World!” 也將被輸出，因為以哈希符號開頭的行被解釋器視為多行註釋。

什麼是行內評論？

Python 中的內聯註釋允許您為特定代碼行提供上下文或解釋。這些類型的註釋與代碼語句放在同一行，由井號 (#) 分隔。

以下是 Python 中的內聯註釋示例：

x = 10  # This variable stores the value 10
y = x * 2  # Multiply x by 2 to get the value of y
print(y)  # Output the value of y

行內註釋應該謹慎使用，只有在需要解釋特定代碼行時才使用。如果您的代碼需要大量的內聯註釋，請考慮使用更具描述性的變量或函數名稱，使代碼本身更清晰、更不言自明。

什麼是文檔字符串？

Docstrings 是有效記錄代碼的重要工具。它們幫助您和其他開發人員理解您的代碼如何運行及其預期目的。

通過將文檔字符串合併到您的 Python 程序中，您可以創建清晰、簡潔和有用的解釋，從而大大提高代碼的可讀性和可維護性。

這種做法促進了開發人員之間更好的協作和溝通，最終提高了您創建的軟件的質量。

Python 中有三種類型的文檔字符串，它們都具有相同的語法但不同的用例：

1. 函數和方法文檔字符串

2. 類文檔字符串

3. 類文檔字符串

函數和方法文檔字符串

函數和方法文檔字符串描述函數或方法的目的、參數、返回值和副作用。

以下是函數和方法文檔字符串的示例：

def add(a, b):
    """Add two numbers and return the result."""
    return a + b

此文檔字符串應始終提供對該函數的簡潔但信息豐富的描述。

類文檔字符串

類文檔字符串解釋了 Python 中類的用途和行為。

以下是使用類文檔字符串來解釋 Python 中類的用途和行為的示例。

class MyClass:
    """A simple class to demonstrate docstrings."""
    
    def __init__(self, x):
        self.x = x

文檔字符串應概述類的功能、它可能具有的任何重要屬性或屬性，以及它如何與程序中的其他類或函數交互。

模塊文檔字符串

模塊文檔字符串應放在 Python 模塊或模塊文件的開頭，提供模塊用途及其內容的全面概述。

通過包含一個編寫良好的模塊文檔字符串，您可以讓開發人員快速確定您的模塊如何適應項目的整體架構以及它提供的特定功能。

這種做法不僅增強了代碼的可讀性和可維護性，而且還促進了在同一項目上工作的團隊成員之間更好的協作和理解。

以下是使用模塊文檔字符串將文檔與 Python 文件相關聯的示例：

"""
geometry.py

This module contains functions to calculate the area of various geometric shapes,
such as rectangles, circles, and triangles. The main functions provided are:

- rectangle_area(width, height)
- circle_area(radius)
- triangle_area(base, height)

Each function takes the respective dimensions as input and returns the calculated area.
"""

def rectangle_area(width, height):
    return width * height

def circle_area(radius):
    import math
    return math.pi * (radius ** 2)

def triangle_area(base, height):
    return 0.5 * base * height

# Rest of the code...

模塊的主要特性及其包含的任何重要變量、類或函數。

撰寫評論的最佳實踐

好的，現在您對 Python 中的不同類型的註釋以及如何使用它們有了一個很好的了解，讓我們看看一些保持高標準工作的最佳實踐。

清晰簡潔

在用 Python 編寫註釋時，必須在清晰和簡潔之間取得平衡。旨在以一種易於理解的方式表達您的想法，同時確保評論保持簡短和信息豐富。

避免包含不必要的信息，以防止評論變得過於冗長和難以維護，這最終會導致混亂。

精心設計的註釋應該毫不費力地與您的代碼集成，增強可讀性和可維護性。

避免明顯的評論

在 Python 中編寫任何註釋時，避免明顯的描述很重要。與其簡單地重述或複制代碼的作用，不如專注於提供可能無法從代碼本身明顯看出的見解。

這適用於編寫單行註釋，也適用於多行註釋。

為了說明這一點，請考慮以下示例，該示例將明顯的評論與更有用的替代方案進行了對比：

# Bad comment
x = x + 1  # Increment x by 1

# Good comment
x = x + 1  # Adjust x to account for the new user added

在代碼更改時更新註釋

隨著代碼的發展，維護更新的 Python 註釋。過時的評論可能會誤導並引起混淆。在對代碼進行重大更改時，請相應地調整 Python 註釋以保持可讀性和易理解性。

想要加深您的 Python 知識，請查看下面我們內容豐富的 Python 視頻。

結論

註釋您的代碼有多種好處，例如幫助理解、維護以及為合作者提供有價值的文檔。

為確保評論有效：

1. 保持評論簡潔、相關和信息豐富。

2. 使用井號 (#) 後跟一個空格作為單行註釋。

3. 使用引號（“””””）來寫多行註釋

4. 為上下文或解釋使用內聯和塊註釋。

5. 隨著代碼的發展更新註釋以保持可讀性。

6. 練習編寫深思熟慮的註釋以提高編程技能。

通過始終如一地使用精心設計的註釋，您不僅可以幫助自己和他人，還可以提升您的編程專業知識。

此外，通過關注評論質量並將有價值的見解融入您的評論中，您將成為更有效率、更有條理和更專業的編碼人員，從而更容易與他人協作並從長遠來看維護您的代碼。