Java 代碼註釋規範全攻略：從基礎到 Javadoc 實戰

為何註釋至關重要？

良好的註釋是專案可維護性的基石。隨著團隊擴大、代碼迭代，統一的註釋風格能降低認知負擔、加速新人上手、輔助自動化文檔生成。

基本原則

1. 風格統一：全專案採用同一標點、縮排、標籤風格；若接手舊專案，遵循既有規範而非強行引入新標準。
2. 內容精準簡潔：避免歧義、錯誤或過時資訊；錯誤的註釋比無註釋更有害。
3. 必須註釋的對象：
   • 類/介面、建構子、公共方法、全域變數、欄位/屬性
   • 簡單 getter/setter、DTO/VO 類可省略
4. 特殊情況必加：
   • 經典演算法、複雜邏輯、非顯而易見處
   • 修改標記（作者、日期、原因、Issue 編號）
   • 迴圈/分支關鍵邏輯
   • 對外公開 API（需完整 Javadoc）

三種註釋語法

Javadoc 核心標籤

/**
 * 類描述：用於操作陣列的工具類，提供最值查找等常用功能。
 * @author 張三
 * @version 1.2
 * @see java.util.Arrays
 */
public class ArrayTool {

    /**
     * 獲取整型陣列的最大值
     * @param arr 輸入陣列，元素為 int
     * @return 陣列最大元素值；若陣列為空拋出 IllegalArgumentException
     * @throws IllegalArgumentException 當 arr 為 null 或 length == 0
     */
    public int getMax(int[] arr) {
        if (arr == null || arr.length == 0)
            throw new IllegalArgumentException("陣列不可為空");
        int max = arr[0];
        for (int v : arr) if (v > max) max = v;
        return max;
    }
}

常用標籤速查

• @author 作者
• @version 版本
• @param <名稱> <說明> 方法參數
• @return <說明> 返回值
• @throws <異常類> <觸發條件> 拋出異常
• @see <參考> 相關連結
• @since <版本> 起始版本
• @deprecated <說明> 棄用標記

生成與查看文檔

# 專案根目錄執行
javadoc -d docs -encoding UTF-8 -charset UTF-8 -sourcepath src -subpackages com.yourpkg
# 瀏覽 docs/index.html

實戰建議

1. IDE 設定「保存時自動格式化註釋」與「缺少 Javadoc 警告」。
2. 建構專案時納入 javadoc 任務，發布成品附帶 API 文檔。
3. 註釋與代碼同步更新：重構時同步修改註釋，避免「註釋撒謊」。
4. 內部私有方法可用簡潔單行註釋；公開 API 必須完整 Javadoc。