整理 Effective Java 書中 Item 56: Write doc comments for all exposed API elements 心得筆記

主旨

寫 Java 程式時，若要讓 API 好用、好維護，註解文件不可或缺。Java 提供的 JavaDoc 工具讓我們能直接從原始碼產生 API 文件，但前提是你要在類別、方法、欄位前寫好符合格式的「doc comment」。本篇說明該怎麼寫註解才真正有幫助，該注意的格式細節與常見錯誤。

為什麼要寫 JavaDoc 註解？

Java 的 JavaDoc 工具能自動產生 API 文件，但它只能根據寫的註解輸出內容。**如果沒有寫註解，文件就什麼都沒有。**對使用者來說很痛苦，對日後自己維護來說也是災難。

舉例來說，如果 public class 或 method 沒有註解，那別人只能猜這功能是幹嘛的，或去翻 source code，非常浪費時間。

基本格式與寫法

註解格式是：

/**
 * 說明文字（第一句會變成簡短摘要）
 *
 * @param 參數名稱 描述這個參數是什麼
 * @return 回傳值的說明（如果是 void 可以省略）
 * @throws 拋出的例外條件
 */

範例如下：

/**
 * 回傳此清單中指定位置的元素。
 *
 * <p>這方法<strong>不保證</strong>是 O(1) 時間複雜度。
 *
 * @param index 要取出的元素位置（從 0 開始）
 * @return 指定位置的元素
 * @throws IndexOutOfBoundsException 如果 index 超出範圍
 */
E get(int index);

幾個重點格式注意：

  • @param、@return 等後面不加句號
  • 使用 <p>、<i> 等 HTML 標籤做排版
  • 若有 < 等 HTML 特殊字元，要用 {@literal <} 或 {@code <} 包起來

特殊標籤的用途

  • {@code ...}：用 monospace 字體顯示程式碼並跳過 HTML 解析
  • {@literal ...}：跳過 HTML 解析，但不套用程式碼字型
  • {@implSpec}：標註方法的實作細節（Java 8 新增）
  • {@index}：用於 API 搜尋索引（Java 9 新增）
  • {@inheritDoc}：繼承父類或介面的註解內容

避免的錯誤寫法與常見問題

註解寫一半

/**
 * 這是一個加總的方法。
 */
int sum(int a, int b); // ← 完全沒有寫 @param 或 @return

這樣文件產生出來只有一行摘要，看不出參數或回傳內容。

不小心讓摘要提早結束

/**
 * 取得學歷，例如 B.S., M.S. 或 Ph.D.
 */

這樣只會顯示「取得學歷，例如 B.S., M.S.」，因為 M.S. 後面有個空格，Javadoc 會斷句。

正確做法：

/**
 * 取得學歷，例如 B.S., {@literal M.S.} 或 Ph.D.
 */

不應該省略的註解

public constructor 不應該省略，否則 JavaDoc 無法顯示註解。

特殊類型的文件寫法

Enum：

/**
 * 管弦樂團的各種樂器組別。
 */
public enum OrchestraSection {
    /** 木管樂器，例如長笛與雙簧管。 */
    WOODWIND,
    /** 銅管樂器，例如法國號與小號。 */
    BRASS
}

Generic：

/**
 * 表示鍵值對映的容器。
 *
 * @param <K> 鍵的型別
 * @param <V> 值的型別
 */
public interface Map<K, V> { ... }

Annotation：

/**
 * 表示此測試方法在成功時需拋出指定的例外。
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface ExceptionTest {
    /**
     * 測試成功時需拋出的例外型別。
     */
    Class<? extends Throwable> value();
}

小結

寫 Java API 的註解不是加分，是基本配備：

  • 所有公開的 class、method、field 都應該寫註解
  • 用 JavaDoc 格式，標準化的文件產出
  • 善用 {@code}、@param、@return 等標籤，提升可讀性
  • 注意細節（HTML 特殊字元、標點、縮排等），避免文件產生錯誤
  • 想成未來的自己是 API 使用者

寫註解是對自己、對團隊、對未來的你最好的習慣。