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

3. 字段注释

字段注释在定义字段的前面,用来描述字段的含义。下面是一个字段注释的例子。
/**
 * 用户名
 */
public String name;
也可以使用如下格式:
/**用户名*/
public String name;
在 Java 的编写过程中我们需要对一些程序进行注释,除了自己方便阅读,更为别人更好理解自己的程序。注释对于程序的可读性来说是非常重要的,希望读者不要忽视它。