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小时内删除侵权内容。