編寫 Java 程式時，不僅要編寫乾淨、高效的程式碼，還要有效地記錄它。在 Java 中執行此操作的一種方法是使用 JavaDoc，這是一個內建工具，可根據程式碼中的註解產生 HTML 文件。該文件對於其他開發人員（甚至您自己）了解您的程式碼的用途、其參數及其預期結果非常有用。

在這篇文章中，我將引導您了解 JavaDoc 的基礎知識以及如何在 Java 程式中有效地使用它。

為什麼要使用 JavaDoc？

JavaDoc 註解不僅僅是常規註解。它們的結構方式可以幫助您自動為類別、方法和欄位產生使用者友好的 HTML 文件。當在團隊中工作或創建其他人需要了解如何使用您的程式碼的 API 時，這尤其有用。

編寫 JavaDoc 註釋

要編寫 JavaDoc，您可以使用以 /** 開頭並以 */ 結尾的特殊區塊註解。我們來看下面的例子：

package basics;

/**
 * This class demonstrates how to create JavaDoc for a simple Java class.
 * 
 * @author Arshi Saxena
 */
public class CreateJavaDoc {
    /**
     * This method performs a simple addition of three numbers.
     * 
     * @param a -> the first number
     * @param b -> the second number
     * @param c -> the third number
     * @return -> the sum of a, b, and c
     */
    public int add(int a, int b, int c) {
        return a   b   c;
    }
}

分解範例

1. 類別級 JavaDoc:

   • CreateJavaDoc 類別上方的註解區塊給出了該類別的高階描述。
   • 您也可以使用 @author 等標籤來新增有關該類作者的元資料。

2. 方法級 JavaDoc:

   • add方法上方的註解區塊描述了此方法的用途。
   • @param 和 @return 等標籤用於提供有關方法參數和傳回值的詳細資訊。

關鍵 JavaDoc 標籤

以下是一些最常用的 JavaDoc 標籤：

• @author：指定類別的作者。

• @param：描述方法中的參數。

• @return：描述方法的回傳類型。

• @throws 或 @Exception: 描述方法拋出的例外。

• @deprecated：將方法或類別標記為已棄用，這意味著不應再使用它。

• @see：引用另一個方法或類別以獲取更多資訊。

在 IDE 中查看 JavaDoc

如果您使用的是 Eclipse 或 IntelliJ IDEA 之類的 IDE，JavaDoc 註解非常有幫助。您可以將滑鼠懸停在類別和方法上，直接在編輯器中查看 JavaDoc 描述。

最後的想法

編寫清晰、簡潔的 JavaDoc 註解是一項小小的努力，但對於提高程式碼的可讀性和可用性卻大有幫助。無論您是在處理個人專案還是在團隊中協作，使用 JavaDoc 都可以確保您的程式碼有完整的文件記錄並且易於理解。

相關貼文

• Java 基礎：資料類型

• 查看我的陣列面試要點系列，以了解更多有關 Java 程式設計的技巧和見解。

快樂編碼！