Java 註釋完全指南：單行、多行、文檔註釋與 Javadoc 生成

Java 三大註釋類型

良好的代碼註釋是專業開發者的基本素養。Java 提供三種註釋機制，分別服務於不同場景。

1. 單行註釋 //

用於簡短說明，編譯器忽略 // 至行尾的所有內容。

public static void main(String[] args) {
    // 打印輸出到控制台
    System.out.println("FirstJava");
    System.out.print("FirstJava\n");
    // System.out.println("FirstJa\tva"); // 調試時暫時屏蔽代碼
}

2. 多行註釋 /* ... */

適合大段代碼說明或暫時禁用代碼塊，不可嵌套。

/*
public String toString(String content) {
    return content;
}
*/

3. 文檔註釋 /** ... */ —— 重點

結合標準標籤（@param、@return、@author 等），可由 javadoc 工具自動生成專業 API 文檔。

/**
 * Description：這是第一個 Java 程序<br/>
 * Author：泊而至遠<br/>
 * Create Date：2016-02-29<br/>
 * Modified Date：2016-03-01<br/>
 * Modified By：泊而至遠<br/>
 */
public class First {
    /**
     * Description：程序入口點<br/>
     * 參數：字符串數組<br/>
     */
    public static void main(String[] args) {
        System.out.println("FirstJava");
    }

    /**
     * Description：顯示輸出個人信息<br/>
     * @return String：姓名<br/>
     * @param content：個人資料<br/>
     */
    public String toString(String content) {
        return content;
    }
}

技巧：文檔註釋中使用 HTML 標籤（如 <br/>）可實現生成文檔的換行效果。

Javadoc 生成實戰

1. 命令格式：javadoc -d <輸出目錄> <源文件>
2. 示例：javadoc -d doc First.java → 在當前目錄下生成 doc/ 文件夾，打開 doc/index.html 即可瀏覽 API 文檔。

最佳實踐建議

• **類/接口/公共方法** 必須編寫文檔註釋，包含功能描述、參數、返回值、異常、作者、版本等。
• **私有方法/內部邏輯** 使用單行或多行註釋說明「為什麼這樣做」而非「做什麼」。
• 保持註釋與代碼同步更新，過時註釋比無註釋更具誤導性。
• 善用 IDE 插件（如 IntelliJ 的 "Generate Javadoc"）自動生成模板。