Java 代碼註釋規範完整指南：類、屬性、方法、構造器與內部註釋模板

前言

統一的代碼註釋規範是團隊協作、代碼維護、自動化文檔生成的基礎。本文梳理 Java 核心註釋類型的標準模板與實戰應用，涵蓋類、屬性、方法、構造器及方法內部註釋，助力構建可讀、可維護的高質量代碼庫。

一、類註釋（Class Comment）

位置：類定義之前

核心元素：

• 類功能職責描述
• 作者、創建日期
• 版本號、最後修改記錄
• 相關業務模塊/表關聯

標準模板

/**
 * 類功能簡述：用戶服務層，處理用戶註冊、登錄、信息維護等核心業務
 * 
 * @author ZhangSan
 * @version 1.0.0
 * @since 2024-01-15
 * @see UserRepository
 * @see UserDTO
 */
public class UserServiceImpl implements UserService { ... }

二、屬性/字段註釋（Field Comment）

位置：字段聲明之前

核心元素：

• 業務含義說明
• 取值範圍/枚舉值引用
• 默認值、是否可空
• 關聯表字段映射

標準模板

/**
 * 用戶狀態：0-禁用，1-啟用，2-鎖定
 * 對應表字段：sys_user.status
 */
private Integer status = 1;

/**
 * 最後登錄時間，格式：yyyy-MM-dd HH:mm:ss
 * 為空表示從未登錄
 */
private Date lastLoginTime;

三、方法註釋（Method Comment）

位置：方法簽名之前

核心元素（Javadoc 標準標籤）：

標準模板

/**
 * 根據用戶ID查詢用戶詳情
 * 
 * @param userId 用戶唯一標識，必填，長度 32 位 UUID
 * @return UserDTO 用戶詳情對象，用戶不存在時返回 null
 * @throws BusinessException 用戶ID格式非法時拋出，錯誤碼：PARAM_INVALID
 * @see UserRepository#findById(String)
 */
public UserDTO getUserById(String userId) { ... }

四、構造器註釋（Constructor Comment）

位置：構造器簽名之前

核心元素：

• 構造器用途（全參/部分參數/構建器模式）
• 參數說明同 @param
• 初始化邏輯特殊說明（如線程池啟動、資源預加載）

標準模板

/**
 * 全參構造器，用於從持久層構建領域對象
 * 
 * @param id           主鍵ID
 * @param username     用戶名，唯一索引
 * @param email        郵箱，已驗證
 * @param createTime   創建時間，不可為空
 */
public User(String id, String username, String email, Date createTime) {
    this.id = id;
    this.username = username;
    this.email = email;
    this.createTime = createTime;
}

五、方法內部註釋（Inline Comment）

原則：解釋「為什麼這樣做」，而非「做了什麼」（代碼本身應自説明）

分類與示例

六、工程化落地建議

1. IDE 模板配置：IntelliJ IDEA → Settings → Editor → File and Code Templates 設置統一模板
2. Checkstyle/SpotBugs 集成：CI 流程強制檢查公共 API 註釋覆蓋率
3. 文檔生成：mvn javadoc:javadoc 生成 HTML 文檔，發布至內部文檔站
4. Code Review 清單：新增公共類/方法必檢查註釋完整性

七、常見反模式

• ❌ 註釋與代碼不一致（修改代碼未同步更新註釋）
• ❌ 無意義註釋：// 設置名字 + setName(name)
• ❌ 過度註釋：私有輔助方法、臨時變量無需 Javadoc
• ❌ HTML 標籤濫用：<b>、<font> 破壞文檔渲染

總結

優秀的註釋是給「六個月後的自己」和「接手的同事」寫的文檔。遵循「公共 API 全覆蓋、業務邏輯重解釋、格式統一工具化」三原則，將註釋從負擔轉化為資產。