註釋（comment）

在Java的編寫過程中我們需要對一些程式進行註釋，除了自己方便閱讀，更為別人更好理解自己的程式，所以我們需要進行一些註釋，可以是程式設計思路或者是程式的作用，總而言之就是方便自己他人更好的閱讀。

註釋是對程式語言的說明，有助於開發者和使用者之間的交流，方便理解程式。註釋不是程式設計語句，因此被編譯器忽略。

單行註釋

單行註釋是最常用的註釋方式。以雙斜槓“//”標識，只能註釋一行內容，用在註釋資訊內容少的地方。

public class FirstSample{
	// main 方法，Java 應用程式的入口
	public static void main(String[] args){
		// 向控制檯輸出語句 "Hei,Hei".
		System.out.println("Hei,Hei");
		// 下面這句程式碼被註釋掉了，不會執行！
		// System.out.println("Hei,Hei! Again.");
	}
}
 

多行註釋

多行註釋，註釋內容放到 /* 和 */之間，能註釋很多行的內容。為了可讀性比較好，一般首行和尾行不寫註釋資訊（這樣也比較美觀）

注意：多行註釋可以巢狀單行註釋，但是不能巢狀多行註釋和文件註釋。

public class FirstSample{
	/* 可以註釋一行內容，main 方法，Java 應用程式的入口 */
	public static void main(String[] args){
		System.out.println("Hei,Hei");
		/*
		也可以註釋多行內容
		System.out.println("不知道說什麼了，舉什麼例子好呢？");
		System.out.println("Hei,Hei! Again.");
	        */
	}
}
 

javaDoc 文件註釋

javaDoc 文件註釋： Java 語言提供了專門用於生成文件的註釋。文件註釋是以 "/ ** " 開始，以 "*/"結束的。也能註釋多行內容，一般用在類、方法和變數上面，用來描述其作用。註釋後，滑鼠放在類和變數上面會自動顯示出我們註釋的內容。

Javadoc 是 Sun 公司提供的一種工具，它可以從程式原始碼中抽取類、方法、成員等註釋，然後形成一個和原始碼配套的 API 幫助文件。也就是說，只要在編寫程式時以一套特定的標籤註釋，在程式編寫完成後，通過 Javadoc 就形成了程式的 API 幫助文件。

注意：文件註釋能巢狀單行註釋，不能巢狀多行註釋和文件註釋，一般首行和尾行也不寫註釋資訊。

API 幫助文件相當於產品說明書，而說明書只需要介紹那些供使用者使用的部分，所以 Javadoc 預設只提取 public、protected 修飾的部分。如果要提取 private 修飾的部分，需要使用 -private。

/**
This is a simple class.
@author 作者：夜雨流雲.
@date 日期：2020年8月02日 15:16:31.
@version 1.0
*/
public class FirstSample{
    public static void main(String[] args){
    	System.out.println("Hei,Hei");
    }
}

Javadoc 標籤

Javadoc 工具可以識別文件註釋中的一些特殊標籤，這些標籤一般以@開頭，後跟一個指定的名字，有的也以{@開頭，以}結束。

對兩種標籤格式的說明：

• @tag 格式的標籤（不被{ }包圍的標籤）為塊標籤，只能在主要描述（類註釋中對該類的詳細說明為主要描述）後面的標籤部分（如果塊標籤放在主要描述的前面，則生成 API 幫助文件時會檢測不到主要描述）。
• {@tag} 格式的標籤（由{ }包圍的標籤）為內聯標籤，可以放在主要描述中的任何位置或塊標籤的註釋中。

Javadoc 標籤注意事項：

• Javadoc 標籤必須從一行的開頭開始，否則將被視為普通文字。
• 一般具有相同名稱的標籤放在一起。
• Javadoc 標籤區分大小寫，程式碼中對於大小寫錯誤的標籤不會發生編譯錯誤，但是在生成 API 幫助文件時會檢測不到該註釋內容。

Javadoc命令

Javadoc 用法格式如下：

javadoc [options] [packagenames] [sourcefiles]

對格式的說明：

• options 表示 Javadoc 命令的選項；
• packagenames 表示包名；
• sourcefiles 表示原始檔名。

在 cmd（命令提示符）中輸入javadoc -help就可以看到 Javadoc 的用法和選項（前提是安裝配置了JDK）

Javadoc 命令的常用選項

DOS命令生成API幫助文件

新建一個空白記事本，輸入下列程式碼：

/**
* @author yyly
* @version jdk1.8.0
*/
public class Test{   
    /**     
    * 求輸入兩個引數範圍以內整數的和     
    * @param n 接收的第一個引數，範圍起點     
    * @param m 接收的第二個引數，範圍終點     
    * @return 兩個引數範圍以內整數的和     
    */    
    public int add(int n, int m) {        
        int sum = 0;        
        for (int i = n; i <= m; i++) {            
            sum = sum + i;        
        }        
        return sum;    
    }
} 

將檔案命名為 Test.java，開啟 cmd 視窗，輸入javadoc -author -version Test.java命令。如圖所示。

開啟 Test.java 檔案儲存的位置，會發現多出了一個 Test.html 文件。開啟文件，文件頁面如圖所示。

注意：以上沒有考慮編碼格式的問題，註釋中有漢字可能會亂碼。使用javadoc -encoding UTF-8 -charset UTF-8 Test.java會解決編碼問題。

開發工具生成API幫助文件

1）在 新建一個 Test 類，程式碼如下：

package test;
/**
* @author yyly
* @version jdk1.8.0
*/
public class Test {   
    public static void main(String[] args) {        
        /**         
        * 這是一個輸出語句         
        */        
        System.out.println("這是一段註釋");    
    }
}

注意：程式碼 9~11 行沒有放在類、成員變數或方法之前，所以 Javadoc 會忽略這個註釋。

2）在專案名處單擊滑鼠右鍵，然後選擇Export...，如圖 所示。

3）在彈出視窗中選擇 Java 資料夾，點選 Java 資料夾下面的 Javadoc，然後點選“Next”，如圖 5 所示。

4）選擇你要生成 Javadoc 的專案，更改你想儲存的 API 幫助文件地址（預設為工程目錄下，建議不要修改）。點選“Finish”，如圖所示。

5）點選“Finish”之後會問是否更新 Javadoc 檔案的位置，只需要點選“Yes To All”即可，如圖所示。

6）這時可以看到控制檯輸出生成 Javadoc 的資訊，如圖 所示。

7）開啟儲存的資料夾，找到 Test.html 檔案並開啟，如圖所示。

文件註釋的格式

在編寫文件註釋的過程中，有時需要新增 HTML 標籤，比如：需要換行時，應該使用<br>，而不是一個回車符；需要分段，使用<p>。

例如把上面 Test 類改為以下程式碼：

package test;
/**
* @author yyly<br>
*         ycs
* @version 1.8.0<br>
*          1.9.0
*/
public class Test {    
    public static void main(String[] args) {        
        System.out.println("這是一個註釋");    
    }
}

Javadoc 並不是將程式碼中的文件註釋直接複製到幫助文件的 HTML 檔案中，而是讀取每一行後，刪除前面的*號及*以前的空格再輸入到 HTML 文件。

/**
\* first line.
******* second line.
\* third line.
*/

編譯輸出後的 HTML 原始碼如下所示。

first line. <br>
second line. <br>
third line.

註釋前面的*號允許連續使用多個，其效果和使用一個*號一樣，但多個*前不能有其他字元分隔，否則分隔符及後面的*號都將作為文件的內容。

總結

一個程式的可讀性，關鍵取決於註釋。如果一個程式想二次開發，要讀懂前面的程式程式碼，就必須在程式中有大量的註釋文件，所以對於一個優秀的程式設計師來說，學會在程式中適當地添加註釋是非常重要的。

註釋除了幫助別人瞭解編寫的程式之外，還對程式的除錯、校對等有相當大的幫助。

當程式具體執行時，計算機會自動忽略註釋符號之後所有的內容。

紹類、方法、欄位等地方的註釋方法，這些地方的註釋雖然簡單但是在開發工作中卻是非常重要的。

• 一行註釋以雙斜槓“//”標識，當編譯器執行到“//”時，就會忽略該行“//”之後的所有文字；
• 多行註釋包含在“/”和“/”之間，當編譯器執行到“/*”時，會掃描下一個“*/”並忽略“/*”和“*/”之間的任何文字；
• 文件註釋包含在“/**”和“*/”之間，當編譯器執行到“/**”時，也會掃描下一個“*/”並忽略“/**”和“*/”之間的任何文字內容。

類註釋

類註釋一般必須放在所有的“import”語句之後，類定義之前，主要宣告該類可以做什麼，以及建立者、建立日期、版本和包名等一些資訊。以下是一個類註釋的模板。

/** 
* @projectName（專案名稱）: project_name 
* @package（包）: package_name.file_name 
* @className（類名稱）: type_name 
* @description（類描述）: 一句話描述該類的功能 
* @author（建立人）: user  
* @createDate（建立時間）: datetime   
* @updateUser（修改人）: user  
* @updateDate（修改時間）: datetime 
* @updateRemark（修改備註）: 說明本次修改內容 
* @version（版本）: v1.0 */

提示：以上以@開頭的標籤為 Javadoc 標記，由@和標記型別組成，缺一不可。@和標記型別之間有時可以用空格符分隔，但是不推薦用空格符分隔，這樣容易出錯。

一個類註釋的建立人、建立時間和描述是不可缺少的。下面是一個類註釋的例子。

/** 
* @author: zhangsan 
* @createDate: 2018/10/28 
* @description: this is the student class. 
*/
public class student{    
    .................
}

注意：沒有必要在每一行的開始用*。例如，以下注釋同樣是合法的：

/**   
@author: zhangsan   
@createDate: 2018/10/28   
@description: this is the student class. 
*/
public class student{    
    .................
}

方法註釋

方法註釋必須緊靠在方法定義的前面，主要宣告方法引數、返回值、異常等資訊。除了可以使用通用標籤外，還可以使用下列的以@開始的標籤。

• @param 變數描述：對當前方法的引數部分新增一個說明，可以佔據多行。一個方法的所有 @param 標記必須放在一起。
• @return 返回型別描述：對當前方法新增返回值部分，可以跨越多行。
• @throws 異常類描述：表示這個方法有可能丟擲異常。有關異常的詳細內容將在第 10 章中討論。

下面是一個方法註釋的例子。

/** 
* @param num1: 加數1 
* @param num2: 加數2 
* @return: 兩個加數的和 
*/
public int add(int num1,int num2) {    
    int value = num1 + num2;    
    return value;
}

以上程式碼的 add() 方法中聲明瞭兩個形參，並將它們兩個的和作為返回值返回。

為類的構造方法添加註釋時，一般宣告該方法的引數資訊，程式碼如下。

public class Student {   
    String name;   int age;   
    /**    
    * @description: 構造方法    
    * @param name: 學生姓名    
    * @param age: 學生年齡    
    */   
    public Student(String name,int age) {   
        this.name = name;    
        this.age = age;   
    }
}

欄位註釋

欄位註釋在定義欄位的前面，用來描述欄位的含義。下面是一個欄位註釋的例子。

/** 
* 使用者名稱 
*/
public String name;

也可以使用如下格式：

//使用者名稱
public String name;

在 Java 的編寫過程中我們需要對一些程式進行註釋，除了自己方便閱讀，更為別人更好理解自己的程式。註釋對於程式的可讀性來說是非常重要的，希望讀者不要忽視它。