Java 註解 (Comments)

註解是程式碼中的說明文字，編譯器會忽略註解內容，不會影響程式執行。

單行註解

使用 // 開頭，該行之後的內容都是註解：

// 這是單行註解
int x = 5;  // 變數 x 存放數字 5

// System.out.println("這行不會執行");

多行註解

使用 /* 開頭，*/ 結尾：

/* 這是多行註解
   可以跨越多行
   用來說明較長的內容 */

int y = 10;

/*
 * 這種格式也很常見
 * 每行前面加上星號
 * 增加可讀性
 */

文件註解

使用 /** 開頭，*/ 結尾，可以用來產生 API 文件：

/**
 * 計算兩數相加
 * @param a 第一個數字
 * @param b 第二個數字
 * @return 兩數的和
 */
public int add(int a, int b) {
    return a + b;
}

常用文件註解標籤

類別文件註解範例

/**
 * 學生類別，用於儲存學生資訊
 * 
 * @author Mike
 * @version 1.0
 * @since 2024-01-01
 */
public class Student {
    
    /**
     * 學生姓名
     */
    private String name;
    
    /**
     * 建立學生物件
     * @param name 學生姓名
     */
    public Student(String name) {
        this.name = name;
    }
    
    /**
     * 取得學生姓名
     * @return 學生姓名
     */
    public String getName() {
        return name;
    }
}

註解的用途

1. 說明程式碼

// 計算圓面積：π * r²
double area = Math.PI * radius * radius;

2. 暫時停用程式碼

public void process() {
    step1();
    // step2();  // 暫時跳過這個步驟
    step3();
}

3. TODO 標記

// TODO: 之後需要優化這段程式碼
// FIXME: 這裡有 bug 需要修復

註解的最佳實踐

好的註解：

// 使用二分搜尋法提高效率，時間複雜度 O(log n)
int index = binarySearch(array, target);

不好的註解（說明顯而易見的事）：

// 將 x 加 1
x++;

// 印出 Hello
System.out.println("Hello");

程式碼本身應該要有良好的可讀性，註解是用來解釋「為什麼」這樣做，而不是解釋「做什麼」。