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{ ................. }

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

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

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

1

2

3

4

5

6

7

8

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

1

2

3

4

5

6

7

8

9

以上代碼的 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

2

3

4

5

6

7

8

9

10

11

12

13

字段注釋

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

/** * 用戶名 */ public String name;

1

2

3

4

也可以使用如下格式：

/**用戶名*/ public String name;

1

2

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

Java

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。

版權聲明：本文內容由網絡用戶投稿，版權歸原作者所有，本站不擁有其著作權，亦不承擔相應法律責任。如果您發現本站中有涉嫌抄襲或描述失實的內容，請聯系我們jiasou666@gmail.com 處理，核實后本網站將在24小時內刪除侵權內容。