MyEclipse/Java 代碼註釋模板配置指南：提升團隊文檔規範化

統一的代碼註釋模板能顯著提升代碼可讀性、便於生成 API 文檔、滿足審計合規要求。本文提供 MyEclipse/Eclipse 中完整的註釋模板配置方案，覆蓋文件、類、字段、構造器、方法、Getter/Setter 等所有場景。

一、快速啟用註釋

選中類/方法/字段 → Alt + Shift + J 自動生成對應模板註釋。

二、模板配置路徑

Window → Preferences → Java → Code Style → Code Templates → Comments

展開各節點編輯模板，變量語法：${variable_name}。

三、常用內建變量速查

四、推薦模板內容（可直接複製）

1. Files（文件頭註釋）

/**
 * @Title: ${file_name}
 * @Package ${package_name}
 * @Description: ${todo}
 * @author ${user}
 * @date ${date} ${time}
 * @version V1.0
 * @copyright Copyright (c) 2024, Company Name All Rights Reserved.
 */

2. Types（類/介面/枚舉註釋）

/**
 * @ClassName: ${type_name}
 * @Description: ${todo}
 * @author ${user}
 * @date ${date} ${time}
 * @version V1.0
 */

3. Fields（字段/屬性註釋）

/**
 * @field ${field}: ${todo}
 */

4. Constructors（構造器註釋）

/**
 * @Description: ${todo}
 * ${tags}
 */

5. Methods（普通方法註釋）

/**
 * @Description: ${todo}
 * ${tags}
 * @return ${return_type}
 * @throws ${exception}
 * @author ${user}
 * @date ${date} ${time}
 */

6. Getter 方法註釋

/**
 * @return ${bare_field_name}
 */

7. Setter 方法註釋

/**
 * @param ${param} ${bare_field_name}
 */

五、團隊落地建議

1. 導出配置：Preferences → Import/Export → Export all settings → 勾選 Code Templates → 導出 .epf 文件，團隊統一導入。
2. 代碼審查清單：檢查公共 API 是否包含 @Description、@param、@return、@throws、@author、@date。
3. 結合 Checkstyle：強制要求 Javadoc 覆蓋率，防止模板生成後未填寫實際描述。
4. 版本號策略：文件級 @version 遵循語義化版本；類級可選，建議僅在重大重構時更新。

六、進階：自定義變量與腳本

Eclipse 支援在模板中調用 Java 代碼片段（${var:java('return ...')}），例如自動生成 @since 標籤：

@since ${project_version:java('return project.getProperty("version");')}

需在 Window → Preferences → Java → Editor → Templates 定義自定義模板變量，較複雜場景建議使用外部文檔生成工具（如 Asciidoctor + Maven 插件）。

規範的註釋模板是技術債務治理的「斷路器」，一次配置，長期受益。建議將模板文件納入項目代碼倉庫（.settings/ 目錄或專門的 eclipse-templates/ 文件夾），隨版本演進同步更新。