注釋?zhuān)╟omment）

在Java的編寫(xiě)過(guò)程中我們需要對(duì)一些程序進(jìn)行注釋?zhuān)俗约悍奖汩喿x，更為別人更好理解自己的程序，所以我們需要進(jìn)行一些注釋?zhuān)梢允蔷幊趟悸坊蛘呤浅绦虻淖饔?，總而言之就是方便自己他人更好的閱讀。

注釋是對(duì)程序語(yǔ)言的說(shuō)明，有助于開(kāi)發(fā)者和用戶(hù)之間的交流，方便理解程序。注釋不是編程語(yǔ)句，因此被編譯器忽略。

單行注釋

單行注釋是最常用的注釋方式。以雙斜杠“//”標(biāo)識(shí)，只能注釋一行內(nèi)容，用在注釋信息內(nèi)容少的地方。

public class FirstSample{
    // main 方法，Java 應(yīng)用程序的入口
    public static void main(String[] args){
        // 向控制臺(tái)輸出語(yǔ)句 "Hei,Hei".
        System.out.println("Hei,Hei");
        // 下面這句代碼被注釋掉了，不會(huì)執(zhí)行！
        // System.out.println("Hei,Hei! Again.");
    }
}

多行注釋

多行注釋?zhuān)⑨寖?nèi)容放到 /* 和 */之間，能注釋很多行的內(nèi)容。為了可讀性比較好，一般首行和尾行不寫(xiě)注釋信息（這樣也比較美觀(guān)）

注意：多行注釋可以嵌套單行注釋?zhuān)遣荒芮短锥嘈凶⑨尯臀臋n注釋。

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

javaDoc 文檔注釋

javaDoc 文檔注釋?zhuān)?Java 語(yǔ)言提供了專(zhuān)門(mén)用于生成文檔的注釋。文檔注釋是以 "/ ** " 開(kāi)始，以 "*/"結(jié)束的。也能注釋多行內(nèi)容，一般用在類(lèi)、方法和變量上面，用來(lái)描述其作用。注釋后，鼠標(biāo)放在類(lèi)和變量上面會(huì)自動(dòng)顯示出我們注釋的內(nèi)容。

Javadoc 是 Sun 公司提供的一種工具，它可以從程序源代碼中抽取類(lèi)、方法、成員等注釋?zhuān)缓笮纬梢粋€(gè)和源代碼配套的 API 幫助文檔。也就是說(shuō)，只要在編寫(xiě)程序時(shí)以一套特定的標(biāo)簽注釋?zhuān)诔绦蚓帉?xiě)完成后，通過(guò) Javadoc 就形成了程序的 API 幫助文檔。

注意：文檔注釋能嵌套單行注釋?zhuān)荒芮短锥嘈凶⑨尯臀臋n注釋?zhuān)话闶仔泻臀残幸膊粚?xiě)注釋信息。

API 幫助文檔相當(dāng)于產(chǎn)品說(shuō)明書(shū)，而說(shuō)明書(shū)只需要介紹那些供用戶(hù)使用的部分，所以 Javadoc 默認(rèn)只提取 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 標(biāo)簽

Javadoc 工具可以識(shí)別文檔注釋中的一些特殊標(biāo)簽，這些標(biāo)簽一般以@開(kāi)頭，后跟一個(gè)指定的名字，有的也以{@開(kāi)頭，以}結(jié)束。

對(duì)兩種標(biāo)簽格式的說(shuō)明：

• @tag 格式的標(biāo)簽（不被{ }包圍的標(biāo)簽）為塊標(biāo)簽，只能在主要描述（類(lèi)注釋中對(duì)該類(lèi)的詳細(xì)說(shuō)明為主要描述）后面的標(biāo)簽部分（如果塊標(biāo)簽放在主要描述的前面，則生成 API 幫助文檔時(shí)會(huì)檢測(cè)不到主要描述）。
• {@tag} 格式的標(biāo)簽（由{ }包圍的標(biāo)簽）為內(nèi)聯(lián)標(biāo)簽，可以放在主要描述中的任何位置或塊標(biāo)簽的注釋中。

Javadoc 標(biāo)簽注意事項(xiàng)：

• Javadoc 標(biāo)簽必須從一行的開(kāi)頭開(kāi)始，否則將被視為普通文本。
• 一般具有相同名稱(chēng)的標(biāo)簽放在一起。
• Javadoc 標(biāo)簽區(qū)分大小寫(xiě)，代碼中對(duì)于大小寫(xiě)錯(cuò)誤的標(biāo)簽不會(huì)發(fā)生編譯錯(cuò)誤，但是在生成 API 幫助文檔時(shí)會(huì)檢測(cè)不到該注釋內(nèi)容。

Javadoc命令

Javadoc 用法格式如下：

javadoc?[options]?[packagenames]?[sourcefiles]

對(duì)格式的說(shuō)明：

• options 表示 Javadoc 命令的選項(xiàng)；
• packagenames 表示包名；
• sourcefiles 表示源文件名。

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

Javadoc 命令的常用選項(xiàng)

DOS命令生成API幫助文檔

新建一個(gè)空白記事本，輸入下列代碼：

/**
* @author yyly
* @version jdk1.8.0
*/
public class Test{   
    /**     
    * 求輸入兩個(gè)參數(shù)范圍以?xún)?nèi)整數(shù)的和     
    * @param n 接收的第一個(gè)參數(shù)，范圍起點(diǎn)     
    * @param m 接收的第二個(gè)參數(shù)，范圍終點(diǎn)     
    * @return 兩個(gè)參數(shù)范圍以?xún)?nèi)整數(shù)的和     
    */    
    public int add(int n, int m) {        
        int sum = 0;        
        for (int i = n; i <= m; i++) {            
            sum = sum + i;        
        }        
        return sum;    
    }
} 

將文件命名為 Test.java，打開(kāi) cmd 窗口，輸入javadoc -author -version Test.java命令。如圖所示。

img

打開(kāi) Test.java 文件存儲(chǔ)的位置，會(huì)發(fā)現(xiàn)多出了一個(gè) Test.html 文檔。打開(kāi)文檔，文檔頁(yè)面如圖所示。

img

注意：以上沒(méi)有考慮編碼格式的問(wèn)題，注釋中有漢字可能會(huì)亂碼。使用javadoc -encoding UTF-8 -charset UTF-8 Test.java會(huì)解決編碼問(wèn)題。

開(kāi)發(fā)工具生成API幫助文檔

1）在 新建一個(gè) Test 類(lèi)，代碼如下：

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

注意：代碼 9~11 行沒(méi)有放在類(lèi)、成員變量或方法之前，所以 Javadoc 會(huì)忽略這個(gè)注釋。

2）在項(xiàng)目名處單擊鼠標(biāo)右鍵，然后選擇Export...，如圖 所示。

img

3）在彈出窗口中選擇 Java 文件夾，點(diǎn)擊 Java 文件夾下面的 Javadoc，然后點(diǎn)擊“Next”，如圖 5 所示。

img

4）選擇你要生成 Javadoc 的項(xiàng)目，更改你想保存的 API 幫助文檔地址（默認(rèn)為工程目錄下，建議不要修改）。點(diǎn)擊“Finish”，如圖所示。

img

5）點(diǎn)擊“Finish”之后會(huì)問(wèn)是否更新 Javadoc 文件的位置，只需要點(diǎn)擊“Yes To All”即可，如圖所示。

img

6）這時(shí)可以看到控制臺(tái)輸出生成 Javadoc 的信息，如圖 所示。

img

7）打開(kāi)保存的文件夾，找到 Test.html 文件并打開(kāi)，如圖所示。

img

文檔注釋的格式

在編寫(xiě)文檔注釋的過(guò)程中，有時(shí)需要添加 HTML 標(biāo)簽，比如：需要換行時(shí)，應(yīng)該使用<br>，而不是一個(gè)回車(chē)符；需要分段，使用<p>。

例如把上面 Test 類(lèi)改為以下代碼：

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("這是一個(gè)注釋");    
    }
}

Javadoc 并不是將代碼中的文檔注釋直接復(fù)制到幫助文檔的 HTML 文件中，而是讀取每一行后，刪除前面的*號(hào)及*以前的空格再輸入到 HTML 文檔。

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

編譯輸出后的 HTML 源碼如下所示。

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

注釋前面的*號(hào)允許連續(xù)使用多個(gè)，其效果和使用一個(gè)*號(hào)一樣，但多個(gè)*前不能有其他字符分隔，否則分隔符及后面的*號(hào)都將作為文檔的內(nèi)容。

總結(jié)

一個(gè)程序的可讀性，關(guān)鍵取決于注釋。如果一個(gè)程序想二次開(kāi)發(fā)，要讀懂前面的程序代碼，就必須在程序中有大量的注釋文檔，所以對(duì)于一個(gè)優(yōu)秀的程序員來(lái)說(shuō)，學(xué)會(huì)在程序中適當(dāng)?shù)靥砑幼⑨屖欠浅Ｖ匾摹?/p>

注釋除了幫助別人了解編寫(xiě)的程序之外，還對(duì)程序的調(diào)試、校對(duì)等有相當(dāng)大的幫助。

當(dāng)程序具體運(yùn)行時(shí)，計(jì)算機(jī)會(huì)自動(dòng)忽略注釋符號(hào)之后所有的內(nèi)容。

紹類(lèi)、方法、字段等地方的注釋方法，這些地方的注釋雖然簡(jiǎn)單但是在開(kāi)發(fā)工作中卻是非常重要的。

• 一行注釋以雙斜杠“//”標(biāo)識(shí)，當(dāng)編譯器執(zhí)行到“//”時(shí)，就會(huì)忽略該行“//”之后的所有文本；
• 多行注釋包含在“/”和“/”之間，當(dāng)編譯器執(zhí)行到“/*”時(shí)，會(huì)掃描下一個(gè)“*/”并忽略“/*”和“*/”之間的任何文本；
• 文檔注釋包含在“/**”和“*/”之間，當(dāng)編譯器執(zhí)行到“/**”時(shí)，也會(huì)掃描下一個(gè)“*/”并忽略“/**”和“*/”之間的任何文本內(nèi)容。

類(lèi)注釋

類(lèi)注釋一般必須放在所有的“import”語(yǔ)句之后，類(lèi)定義之前，主要聲明該類(lèi)可以做什么，以及創(chuàng)建者、創(chuàng)建日期、版本和包名等一些信息。以下是一個(gè)類(lèi)注釋的模板。

/** 
* @projectName（項(xiàng)目名稱(chēng)）: project_name 
* @package（包）: package_name.file_name 
* @className（類(lèi)名稱(chēng)）: type_name 
* @description（類(lèi)描述）: 一句話(huà)描述該類(lèi)的功能 
* @author（創(chuàng)建人）: user  
* @createDate（創(chuàng)建時(shí)間）: datetime   
* @updateUser（修改人）: user  
* @updateDate（修改時(shí)間）: datetime 
* @updateRemark（修改備注）: 說(shuō)明本次修改內(nèi)容 
* @version（版本）: v1.0 */

提示：以上以@開(kāi)頭的標(biāo)簽為 Javadoc 標(biāo)記，由@和標(biāo)記類(lèi)型組成，缺一不可。@和標(biāo)記類(lèi)型之間有時(shí)可以用空格符分隔，但是不推薦用空格符分隔，這樣容易出錯(cuò)。

一個(gè)類(lèi)注釋的創(chuàng)建人、創(chuàng)建時(shí)間和描述是不可缺少的。下面是一個(gè)類(lèi)注釋的例子。

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

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

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

方法注釋

方法注釋必須緊靠在方法定義的前面，主要聲明方法參數(shù)、返回值、異常等信息。除了可以使用通用標(biāo)簽外，還可以使用下列的以@開(kāi)始的標(biāo)簽。

• @param 變量描述：對(duì)當(dāng)前方法的參數(shù)部分添加一個(gè)說(shuō)明，可以占據(jù)多行。一個(gè)方法的所有 @param 標(biāo)記必須放在一起。
• @return 返回類(lèi)型描述：對(duì)當(dāng)前方法添加返回值部分，可以跨越多行。
• @throws 異常類(lèi)描述：表示這個(gè)方法有可能拋出異常。有關(guān)異常的詳細(xì)內(nèi)容將在第 10 章中討論。

下面是一個(gè)方法注釋的例子。

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

以上代碼的 add() 方法中聲明了兩個(gè)形參，并將它們兩個(gè)的和作為返回值返回。

為類(lèi)的構(gòu)造方法添加注釋時(shí)，一般聲明該方法的參數(shù)信息，代碼如下。

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

字段注釋

字段注釋在定義字段的前面，用來(lái)描述字段的含義。下面是一個(gè)字段注釋的例子。

/** 
* 用戶(hù)名 
*/
public String name;

也可以使用如下格式：

//用戶(hù)名
public String name;

在 Java 的編寫(xiě)過(guò)程中我們需要對(duì)一些程序進(jìn)行注釋?zhuān)俗约悍奖汩喿x，更為別人更好理解自己的程序。注釋對(duì)于程序的可讀性來(lái)說(shuō)是非常重要的，希望讀者不要忽視它。