Java - Javadoc Comments: A Beginner's Guide

您好，有志於Java程式設計的您！今天，我們將要踏上探索Javadoc註釋的精彩旅程。別擔心如果您之前從未寫過一行代碼——我將成為您友好的導遊，我們會一步一步地進行。在這個教學結束時，您將能夠像專業人士一樣撰寫出專業看起來的文件！

Java - Javadoc Comments

什麼是Javadoc？

想像您正在寫一本食譜。您不會只列出材料和方法而不加任何解釋，對吧？這就是Java程式設計中Javadoc的用處。它是一個幫助我們為代碼創建有條理、有組織的文件的工具。

Javadoc註釋是您Java代碼中的特殊註釋，它們會被轉換成漂亮的HTML文件。它們就像您會添加到食譜中的額外筆記和小貼士，以幫助他人更好地理解它。

為什麼使用Javadoc？

它讓別人（以及未來的您自己！）更容易理解您的代碼。
它是記錄Java代碼的標準方式，所以其他Java開發者會對此熟悉。
它可以自動生成專業看起來的文件。

Javadoc標籤

Javadoc使用特殊標籤來組織信息。將這些標籤想像成您食譜中的節頭。以下是一些最常見的：

標籤	描述	示例
@author	指定代碼的作者	@author John Doe
@version	指示類的版本	@version 1.0
@param	描述方法參數	@param name 人的名字
@return	描述方法返回什麼	@return 計算出的面積
@throws	列出方法可能抛出的異常	@throws IOException 如果文件無法讀取
@see	添加一個“參見”標題，並提供到其他元素的鏈接	@see String#toLowerCase()
@since	指定此功能添加的時間	@since 1.5
@deprecated	指示此API不再使用	@deprecated 使用newMethod()代替

現在，讓我們看看我們如何在真實的Java代碼中使用這些。

示例 - 使用Javadoc註釋

讓我們創建一個簡單的Rectangle類來演示Javadoc註釋：

/**
* 這個類代表一個矩形形狀。
* 它可以計算矩形的面積和周長。
*
* @author Jane Smith
* @version 1.0
* @since 2023-06-01
*/
public class Rectangle {
private double length;
private double width;

/**
* 使用給定的尺寸構造一個新的Rectangle。
*
* @param length 矩形的長度
* @param width 矩形的寬度
*/
public Rectangle(double length, double width) {
this.length = length;
this.width = width;
}

/**
* 計算並返回矩形的面積。
*
* @return 矩形的面積
*/
public double calculateArea() {
return length * width;
}

/**
* 計算並返回矩形的周長。
*
* @return 矩形的周長
*/
public double calculatePerimeter() {
return 2 * (length + width);
}

/**
* 根據給定的因子調整矩形的大小。
*
* @param factor 調整大小的因子（例如，2.0會使大小翻倍）
* @throws IllegalArgumentException 如果因子為負
*/
public void resize(double factor) throws IllegalArgumentException {
if (factor < 0) {
throw new IllegalArgumentException("調整大小因子必須為正");
}
length *= factor;
width *= factor;
}
}

讓我們分解這個：

類級註釋描述了Rectangle類的作用，並包含了@author、@version和@since標籤。
构造器有一個註釋解釋它做了什麼，並對每個參數使用@param標籤。
calculateArea()和calculatePerimeter()方法有註釋解釋它們做了什麼，並使用@return標籤描述它們返回的內容。
resize()方法展示了如何記錄可能抛出異常的方法，使用@throws標籤。

生成Javadoc HTML

現在來到神奇的部分！當您寫好了Javadoc註釋，可以使用Javadoc工具生成美麗的HTML文件。如果您使用的是像Eclipse或IntelliJ IDEA這樣的集成開發環境（IDE），通常只需單擊一個按鈕即可。

例如，在Eclipse中：

在您的項目上右擊
選擇"生成Javadoc"
跟隨向導設置選項
點擊"完成"

然後，您就會有一套HTML文件，它們以專業、易於導航的格式顯示您的文件。

編寫Javadoc的最佳實踐

清晰簡潔：寫您的註釋時，就像您正在向從未見過您的代碼的人解釋一樣。
記錄公共API：專注於記錄公共類、方法和字段。這些是其他開發者將要使用的。
使用完整的句子：以大寫字母開頭，以句號結尾。這會使文件更易於閱讀。
避免冗余：不要只重複方法名。用您的註釋添加價值。
更新註釋：當您更改代碼時，記得更新相應的Javadoc註釋。

結論

恭喜您！您剛剛踏出了進入Javadoc註釋世界的第一步。記住，好的文件就像為他人（或您未來的自己）留下的麵包屑一樣。現在它可能看起來像是額外的工作，但相信我，六個月後當您回頭看您的代碼時，您會為自己能夠清楚地理解一切而感謝自己。

繼續練習，很快寫Javadoc註釋就會成為您的第二天性。祝您編程愉快，並願您的代碼總是具有良好的文件！

Credits: Image by storyset