在軟體開發團隊中，最常聽到的工程師心聲往往是：「我不喜歡寫文件，但我討厭看別人沒寫文件的代碼。」

在接手既有專案（Legacy System）或多人協作時，常常遇到只有方法名稱、內部邏輯複雜，卻沒有任何一行註解的陳年代碼。如果事後要逐一補齊標準的 JavaDoc、參數規格說明與例外拋出定義，往往需要消耗大半天的工時。

今天我們就來示範：如何讓 ChatGPT / Copilot 扮演技術文件工程師，只需貼上既有類別與函式，就能自動萃取核心語意，生成完全符合業界標準的 JavaDoc 註解與 API 技術規格！

一、JavaDoc 生成專用提示詞模板（Documentation Prompting）

想要讓 AI 產出高水準的技術文件，不要只丟一句「幫我加註解」，而是要指定標準規範與重點標籤：

【JavaDoc 生成提示詞範本】
請扮演資深 Java 技術文件架構師。以下是一段尚未編寫文件說明的商業邏輯代碼：

[貼上既有的 Java 類別或方法]

請為這段代碼補齊符合 Oracle JavaDoc 規範的完整註解，要求如下：

1. 核心職責概述：簡明扼要說明該類別或方法的核心商業目的。
2. 完整標籤標註：精確標記 @param（包含合法取值範圍）、@return（包含空值或特殊值含義）、@throws（列出何種情境會拋出該例外）。
3. 執行緒安全與邊界聲明：標記 Thread-safety 狀態（如 Thread-safe 或 Not Thread-safe）以及時間/空間複雜度。
4. 使用範例（Usage Example）：在註解中使用 {@code ...} 區塊提供 1 個標準調用範例。

二、實戰案例：為未加註解的字串脫敏工具補齊文件

假設我們在專案中找到一個處理個資遮罩（Data Masking）的工具方法，原本完全沒有任何註解：

[補齊註解前：無說明的裸代碼]
public class MaskingUtils {
    public static String maskMobile(String mobile) {
        if (mobile == null || mobile.length() != 10) {
            return mobile;
        }
        return mobile.substring(0, 4) + "***" + mobile.substring(7);
    }
}

三、AI 生成的標準 JavaDoc 註解成果

套用模板後，AI 自動產出了具備完整標籤與邊界說明的 JavaDoc：

[JavaDoc 完整補全代碼]
/**
 * 個資脫敏與遮罩處理工具類別
 * <p>提供常見機敏資訊（如手機門號、身分證號、信用卡號）的顯示遮罩功能。</p>
 *
 * <p><strong>執行緒安全特性：</strong>該類別為無狀態工具類，所有方法均為執行緒安全（Thread-safe）。</p>
 *
 * @author Engineering Team
 * @since 1.0.0
 */
public final class MaskingUtils {

    private MaskingUtils() {
        // 防止工具類別被實例化
    }

    /**
     * 針對台灣 10 碼手機號碼進行中段遮罩處理。
     * <p>將手機號碼第 5 至第 7 碼以星號「***」取代，保留前 4 碼與後 3 碼。</p>
     *
     * <p><b>使用範例：</b></p>
     * <pre>{@code
     * String masked = MaskingUtils.maskMobile("0912345678");
     * // 結果為: "0912***678"
     * }</pre>
     *
     * @param mobile 原始手機號碼字串，需為 10 碼數字格式（例如 "0912345678"）
     * @return 遮罩後的手機字串；若傳入為 {@code null} 或長度不符 10 碼，則直接原樣回傳避免中斷流程
     * @see String#substring(int, int)
     */
    public static String maskMobile(String mobile) {
        if (mobile == null || mobile.length() != 10) {
            return mobile;
        }
        return mobile.substring(0, 4) + "***" + mobile.substring(7);
    }
}

四、進階延伸：從 JavaDoc 一鍵轉出 Markdown / OpenAPI 規格

除了直接嵌入代碼的 JavaDoc，當跨部門（如前端或 QA 團隊）需要接口說明時，我們還可以要求 AI 直接將寫好的 JavaDoc 轉換為 Markdown 文件：

【Markdown 轉譯提示詞】
「請將上方的方法與 JavaDoc 轉換為前端工程師容易閱讀的 Markdown 介面規格表格，包含參數、型別、預設行為與回傳值。」

【AI 轉換產出的 Markdown 表格】

五、工程師在文件維護上的省思

1. 保持註解與代碼同步：
   代碼修改時，最怕註解變成「過時謊言」。利用 AI 進行 Code Review 時，可以順便下達：「請檢查既有 JavaDoc 與當前代碼邏輯是否有出入」，能有效防範註解漂移。
2. 善用 IDE 快捷指令：
   在 VS Code 中選取方法後，使用 Copilot Chat 輸入 /doc，AI 也會立刻在上方就地插入標準 Javadoc 註解骨架。
3. 把時間留給架構設計：
   機械式的格式撰寫（@param、@return）交給 AI，工程師只需專注於確認商業邊界是否被準確描述，大幅釋放工程生產力。

今日小結與預告

今天我們掌握了利用 AI 自動為陳年代碼補全專業 JavaDoc 規格的方法，包含邊界宣告、執行緒安全性說明與使用範例展示，甚至能輕鬆產出團隊協作所需的 Markdown 文件。