寫不好代碼注釋？這份注釋指南一定要收好！

摘要：之前有讀者問，自己一直不明白如何寫出合理的代碼注釋。这也是不少程序员一直头疼的问题，本文就将一些经验分享给大家，希望提供一些幫助。

本篇目錄

之前有讀者問，自己一直不明白如何寫出合理的代碼注釋。

這也是不少程序員一直頭疼的問題，比如接手新代碼時，沒有注釋，完全搞不清邏輯；自己寫的注釋，跟不上代碼修改，成了誤導；複雜邏輯不知道咋注釋，別人也看不懂。

code-comment-guide

（聽君一席話，聽了一席話）

網上也有很多關于代碼注釋的段子，搞笑中透露著真實的注釋現狀，比如下面這些注釋：

code-comment-guide-1

（这也算得上是“风险预警”吧 ↑ ）

code-comment-guide-2

code-comment-guide-3

code-comment-guide-4

（阅读代码的人，心里一定很崩溃 ↑ ）

还有一种是，注释透露着一种自由的随意感：

code-comment-guide-5

我们都知道，注释是代码的重要组成部分，它能够为代码的读者提供额外的信息，幫助他们更好地理解代码的功能、逻辑和设计意图。

寫出合理的注釋不僅能夠提高代碼的可讀性和可維護性，還能促進團隊成員之間的有效協作。

本文就将一些经验分享给大家，希望提供一些幫助。

一、明確注釋的目的

目標設定理論提出：清晰、明確和可衡量的目標比模糊不清的目標更能提高工作效率。目的也同樣。

而我們寫注釋的主要目的是爲了增強代碼的可理解性。下面列出了一些具体的注释目的，在写之前幫助我们理清思路，明确行动方向。

（一）解釋代碼的功能和用途

代碼注釋要讓讀者能夠快速了解一段代碼或一個函數的整體作用。比如，編寫了一個函數用于從數據庫中獲取特定用戶的信息，注釋就可以這麽寫：“此函數用于從數據庫中檢索指定用戶的詳細信息，包括用戶名、電子郵件和年齡等字段。”

實踐要點：

在注釋中明確函數的輸入和輸出格式，例如數據類型、結構等。
提及函數可能抛出的異常或特殊情況。

（二）說明複雜算法或邏輯的工作原理

對于複雜的計算或獨特的邏輯流程，注釋能夠幫助读者理解代码背后的思路。比如，對于一個使用遞歸實現的斐波那契數列計算函數：

def fibonacci(n):
    """
    此函数使用递归算法计算斐波那契数列的第 n 项
    参数:
    n (int): 要计算的项数
    返回:
    int: 斐波那契数列的第 n 项值
    工作原理:
    欧几里得算法的基本思路是：不断用较小数除以较大数，并将余数赋给较小数，直到余数为 0。
    在本函数中，如果 n 小于等于 0，返回 0；如果 n 等于 1，返回 1；
    否则，返回 fibonacci(n - 1) + fibonacci(n - 2)，通过递归计算得出结果
    """
    if n <= 0:
        return 0
    elif n == 1:
        return 1
    else:
        return fibonacci(n - 1) + fibonacci(n - 2)

實踐要點：

對于複雜的算法，繪制簡單的流程圖或架構圖，並在注釋中引用。
解釋算法中的關鍵變量和它們的變化規律。

（三）提供關于特定變量、函數或類的重要信息

解釋變量的含義、函數的輸入輸出以及類的設計目的等。比如：“這個變量 max_attempts 表示嘗試連接數據庫的最大次數。”

假設我們有一個函數用于計算兩個數的最大公約數：

def greatest_common_divisor(a, b):
    """
    此函数用于计算两个整数的最大公约数
    参数:
    a (int): 第一个整数
    b (int): 第二个整数
    返回:
    int: 两个数的最大公约数
    算法: 使用欧几里得算法，其基本步骤为：用较大数除以较小数得到余数，然后将较小数作为新的较大数，余数作为新的较小数，重复此过程，直到余数为 0，此时的除数即为最大公约数
    """
    while b!= 0:
        a, b = b, a % b
    return a

在示例中，就注釋清晰地說明了函數的功能、參數和使用的算法。

實踐要點：

對于類，注釋中描述其繼承關系、主要方法和屬性。
對于函數，說明函數的性能特點，例如時間複雜度和空間複雜度。

二、保持簡潔明了

注釋應該簡潔而准確地傳達關鍵信息。避免過于冗長和複雜的描述，以免增加讀者的理解負擔。例如，不要寫一大段文字來解釋一個簡單的函數，而可以簡潔地說：“此函數計算兩個整數的平均值，並返回結果。”

在這裏，提供一些實踐技巧：

提煉關鍵信息，去除不必要的修飾詞和廢話。
對于簡單的邏輯，用一句話概括注釋。
定期審查注釋，刪除冗余和過時的信息。
對于較長的注釋，將其拆分成多個短句或段落，增強可讀性。

三、采用清晰的語言

使用簡單、易懂的詞彙和句子結構，避免使用行話、縮寫或過于技術化的術語，除非你确定读者一定能理解。所以尽量简单表达，就像在与其他开发者进行交流一样。举个例子，当你在解释一个数据结构时，“这是一个基于链表实现的队列”的表达可能会比说“这是一个采用链表数据结构的 FIFO 队列”更容易被人理解。

在這裏，需要注意以下事項：

保持語言的一致性，避免在同一項目中使用多種表述方式來表達相同的概念。
對于可能有歧義的術語，進行必要的解釋。
建立項目詞彙表，統一關鍵術語的表述。
對于新引入的技術術語，在注釋開頭進行定義和解釋。

四、提供上下文

注釋不僅要描述代碼本身，還要讓讀者了解它在整個程序中的位置和作用。还是举个例子：“此函数在用户登录流程中被调用，用于验证用户输入的密码是否正确。” 这样的注释很明显能够幫助读者将当前代码与程序的更大框架联系起来，幫助读者更快理解代码。

爲了更好理解和掌握，我們來假設一個場景：我們現在有一個處理訂單的模塊，其中有一個函數用于計算訂單的總價：

def calculate_order_total(order_items):
    """
    此函数在订单处理流程中用于计算订单的总价
    参数:
    order_items (list): 包含订单中各项商品信息的列表，其中商品信息以字典形式存储，包括'price'（價格）和'quantity'（数量）两个键
    注意: 此函数会根据商品的'price'和'quantity'进行计算
    """
    total = 0
    for item in order_items:
        total += item['price'] * item['quantity']
    return total

這裏的注釋就明確了函數在整個訂單處理流程中的位置和作用。

實踐要點：

引用相關的業務流程文檔或需求說明，增強注釋的上下文信息。
在注釋中提及與當前代碼相關的其他函數或模塊。

五、遵循統一的風格

在整個項目中，要保持注釋的格式、標點和命名約定的一致性。这包括注释的位置（行末、函数前等）、注释的符号（例如 Python 中常用的 # ）、以及注释的书写方式（是完整的句子还是短语等）。統一的風格可以使注釋看起來更加整潔和專業。

例如，在一个 Python 项目中，规定函数注释采用如下格式：

def some_function(arg1, arg2):
    """
    函数功能的简要描述
    参数:
    arg1 (数据类型) - 参数 1 的描述
    arg2 (数据类型) - 参数 2 的描述
    返回:
    返回值的数据类型 - 返回值的描述
    """
    # 函数体代码

提供一些風格規範的思路：

確定統一的注釋符號和格式。
制定關于注釋內容的詳細規範，如參數描述、返回值描述的格式。
使用工具（如代碼規範檢查插件）來自動檢查注釋風格的一致性。
爲新加入項目的開發者提供詳細的注釋風格指南。

六、注釋關鍵代碼

重點注釋那些容易引起混淆、不常見或對程序的正確性和性能有重要影響的部分。對于簡單和直觀的代碼，或許不需要過多注釋，但對于複雜的條件判斷、循環結構或與外部系統的交互部分，詳細的注釋是很有必要的。還是以例子來直觀解釋下：

def process_data(data):
    """
    此函数处理传入的数据
    参数:
    data (列表) - 包含待处理数据的列表
    以下的条件判断用于处理不同的数据类型
    如果数据是整数列表，执行求和操作
    如果数据是字符串列表，连接所有字符串
    """
    if all(isinstance(item, int) for item in data):
        total = 0
        for num in data:
            total += num
        return total
    elif all(isinstance(item, str) for item in data):
        result = ''
        for string in data:
            result += string
        return result

實踐要點：

分析代碼的複雜度和易錯性。
關注與業務邏輯緊密相關的核心代碼部分。
對于關鍵代碼，添加注釋說明其優化的思路和考慮的因素。
在關鍵代碼的注釋中引用相關的技術文檔或最佳實踐。

七、及時更新注釋

隨著代碼的修改和更新，相應的注釋也必須保持同步。過時或不正確的注釋可能會比沒有注釋更糟糕，因爲它們會誤導讀者。在修改代碼時，務必檢查並更新相關的注釋，確保它們准確反映了代碼的最新狀態。

更新策略：

建立代碼審查機制，確保注釋的更新。
養成在修改代碼的同時更新注釋的習慣。
使用版本控制系統來跟蹤注釋的變更曆史。
在代碼提交信息中說明對注釋的修改內容。

八、示例

對于一些複雜的概念或邏輯，提供簡單的示例可以極大地增強注釋的效果。例如，如果你在解釋一個正則表達式的用法，可以給出幾個匹配和不匹配的示例字符串。

假設我們有一個正則表達式用于驗證電子郵件地址：

import re
email_pattern = r"^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9-.]+$"
def validate_email(email):
    """
    此函数使用正则表达式验证电子邮件地址的有效性
    参数:
    email (str) - 待验证的电子邮件地址
    示例:
    有效电子邮件: "test@example.com", "user123@gmail.com"
    无效电子邮件: "invalid_email", "no_domain@"
    """
    if re.match(email_pattern, email):
        return True
    else:
        return False

實踐要點：