Java的類/方法/字段注釋詳解

一個程式的可讀性，關鍵取決于注釋。如果一個程式想二次開發，要讀懂前面的程式代碼，就必須在程式中有大量的注釋文檔，是以對于一個優秀的程式員來說，學會在程式中适當地添加注釋是非常重要的。

注釋除了幫助别人了解編寫的程式之外，還對程式的調試、校對等有相當大的幫助。當程式具體運作時，計算機會自動忽略注釋符号之後所有的内容。教程第二章中曾經提到過注釋，讀者也許印象不太深，在這裡複習一遍。

本節将簡單地介紹類、方法、字段等地方的注釋方法，這些地方的注釋雖然簡單但是在開發工作中卻是非常重要的。

注意：本節注釋使用文檔注釋。多行注釋的内容不能用于生成一個開發者文檔（文檔提供類、方法和變量的解釋，也可稱為幫助文檔），而文檔注釋可以。

1 類注釋

類注釋一般必須放在所有的“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{
    .................
}      

2. 方法注釋

方法注釋必須緊靠在方法定義的前面，主要聲明方法參數、傳回值、異常等資訊。除了可以使用通用标簽外，還可以使用下列的以@開始的标簽。

@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;
   }
}      

1. 字段注釋

   字段注釋在定義字段的前面，用來描述字段的含義。下面是一個字段注釋的例子。

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

也可以使用如下格式：

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

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