021：Java 类注释

Java 类注释

（转自：http://c.biancheng.net/view/940.html）

1        类注释（掌握）

类注释一般必须放在所有的“import”语句之后，类定义之前，主要声明该类可以做什么，以及创建者、创建日期、版本和包名等一些信息。以下是一个类注释的模板。

1. /**
2.  * @projectName（项目名称）: project_name
3.  * @package（包）: package_name.file_name
4.  * @className（类名称）: type_name
5.  * @description（类描述）: 一句话描述该类的功能
6.  * @author（创建人）: user
7.  * @createDate（创建时间）: datetime 
8.  * @updateUser（修改人）: user
9.  * @updateDate（修改时间）: datetime
10. 10.  * @updateRemark（修改备注）: 说明本次修改内容
11. 11.  * @version（版本）: v1.0
12. 12.  */

提示：以上以@开头的标签为 Javadoc 标记，由@和标记类型组成，缺一不可。@和标记类型之间有时可以用空格符分隔，但是不推荐用空格符分隔，这样容易出错。
一个类注释的创建人、创建时间和描述是不可缺少的。下面是一个类注释的例子。

1. /**
2.  * @author: zhangsan
3.  * @createDate: 2018/10/28
4.  * @description: this is the student class.
5.  */
6. public class student{
7.     .................
8. }

注意：没有必要在每一行的开始用*。例如，以下注释同样是合法的：

1. /**
2.    @author: zhangsan
3.    @createDate: 2018/10/28
4.    @description: this is the student class.
5.  */
6. public class student{
7.     .................
8. }

2. 方法注释

方法注释必须紧靠在方法定义的前面，主要声明方法参数、返回值、异常等信息。除了可以使用通用标签外，还可以使用下列的以@开始的标签。

• @param 变量描述：对当前方法的参数部分添加一个说明，可以占据多行。一个方法的所有 @param 标记必须放在一起。
• @return 返回类型描述：对当前方法添加返回值部分，可以跨越多行。
• @throws 异常类描述：表示这个方法有可能抛出异常。有关异常的详细内容将在第 10 章中讨论。
  下面是一个方法注释的例子。

1. /**
2.  * @param num1: 加数1
3.  * @param num2: 加数2
4.  * @return: 两个加数的和
5.  */
6. public int add(int num1,int num2) {
7.     int value = num1 + num2;
8.     return value;
9. }

以上代码的 add() 方法中声明了两个形参，并将它们两个的和作为返回值返回。
为类的构造方法添加注释时，一般声明该方法的参数信息，代码如下。

1. public class Student {
2.    String name;
3.    int age;
4.    /**
5.     * @description: 构造方法
6.     * @param name: 学生姓名
7.     * @param age: 学生年龄
8.     */
9.    public Student(String name,int age) {
10. 10.     this.name = name;
11. 11.     this.age = age;
12. 12.    }

13. }

3. 字段注释

字段注释在定义字段的前面，用来描述字段的含义。下面是一个字段注释的例子。

1. /**
2.  * 用户名
3.  */
4. public String name;

也可以使用如下格式：

1. /**用户名*/
2. public String name;

在 Java 的编写过程中我们需要对一些程序进行注释，除了自己方便阅读，更为别人更好理解自己的程序。注释对于程序的可读性来说是非常重要的，希望读者不要忽视它。

4. 访问控制修饰符（public、 private、protected 和 friendly）

在实际生活中，如果要获取某件物品，与其直接穿过堡垒的墙壁，从而导致墙壁毁灭和破坏，不如通过门口的警卫请求进入堡垒的许可。一般而言，这对对象同样适用：没有对象的许可（即对象的属性是私有的），不能直接访问该对象的私有属性。
信息隐藏是 OOP 最重要的功能之一，也是使用访问修饰符的原因。在编写程序时，有些核心数据往往不希望被用户调用，需要控制这些数据的访问。
对类成员访问的限制是面向对象程序设计的一个基础，这有利于防止对象的误用。只允许通过一系列定义完善的方法来访问私有数据，就可以（通过执行范围检查）防止数据赋予不正当的值。例如，类以外的代码不可能直接向一个私有成员赋值。同时，还可以精确地控制如何以及何时使用对象中的数据。
当正确实现对类成员的方法控制后，类就可以创建一个可用的“黑箱”，其内部动作不会被打开而任意篡改。
通过使用访问控制修饰符来限制对对象私有属性的访问，可以获得 3 个重要的好处。

• 防止对封装数据的未授权访问。
• 有助于保证数据完整性。
• 当类的私有实现细节必须改变时，可以限制发生在整个应用程序中的“连锁反应”。
  访问控制符是一组限定类、属性或方法是否可以被程序里的其他部分访问和调用的修饰符。类的访问控制符只能是空或者 public，方法和属性的访问控制符有 4 个，分别是 public、 private、protected 和 friendly，其中 friendly 是一种没有定义专门的访问控制符的默认情况。访问控制修饰符的权限如表 1 所示。

表1 各种访问修饰符的可访问性
访问范围	private	friendly(默认)	protected	public
同一个类	可访问	可访问	可访问	可访问
同一包中的其他类	不可访问	可访问	可访问	可访问
不同包中的子类	不可访问	不可访问	可访问	可访问
不同包中的非子类	不可访问	不可访问	不可访问	可访问

访问控制在面向对象技术中处于很重要的地位，合理地使用访问控制符，可以通过降低类和类之间的耦合性（关联性）来降低整个项目的复杂度，也便于整个项目的开发和维护。

在 Java 语言中，访问控制修饰符有 4 种。

1）. private

用 private 修饰的类成员，只能被该类自身的方法访问和修改，而不能被任何其他类（包括该类的子类）访问和引用。因此，private 修饰符具有最高的保护级别。例如，设 PhoneCard 是电话卡类，电话卡都有密码，因此该类有一个密码域，可以把该类的密码域声明为私有成员。

2）. friendly（默认）

如果一个类没有访问控制符，说明它具有默认的访问控制特性。这种默认的访问控制权规定，该类只能被同一个包中的类访问和引用，而不能被其他包中的类使用，即使其他包中有该类的子类。这种访问特性又称为包访问性（package private）。
同样，类内的成员如果没有访问控制符，也说明它们具有包访问性，或称为友元（friend）。定义在同一个文件夹中的所有类属于一个包，所以前面的程序要把用户自定义的类放在同一个文件夹中（Java 项目默认的包），以便不加修饰符也能运行。

3）. protected

用保护访问控制符 protected 修饰的类成员可以被三种类所访问：该类自身、与它在同一个包中的其他类以及在其他包中的该类的子类。使用 protected 修饰符的主要作用，是允许其他包中它的子类来访问父类的特定属性和方法，否则可以使用默认访问控制符。

4）. public

当一个类被声明为 public 时，它就具有了被其他包中的类访问的可能性，只要包中的其他类在程序中使用 import 语句引入 public 类，就可以访问和引用这个类。
类中被设定为 public 的方法是这个类对外的接口部分，避免了程序的其他部分直接去操作类内的数据，实际就是数据封装思想的体现。每个 Java 程序的主类都必须是 public 类，也是基于相同的原因。

例 1

下面来创建一个示例，演示 Java 中访问控制修饰符的使用。
(1) 新建 Student.java 文件，在该文件中定义不同修饰符的属性和方法，代码如下：

1. class Student {
2.     // 姓名，其访问权限为默认(friendly)
3.     String name;
4.  
5.     // 定义私有变量，身份证号码
6.     private String idNumber;
7.  
8.     // 定义受保护变量，学号
9.     protected String no;
10. 10.  
11. 11.     // 定义共有变量，邮箱
12. 12.     public String email;
13. 13.  
14. 14.     // 定义共有方法，显示学生信息
15. 15.     public String info() {
16. 16.         return"姓名："+name+"，身份证号码："+idNumber+"，学号："+no+"，邮箱："+email;
17. 17.     }

18. }

(2) 新建 StudentTest.java 文件，在该文件中定义 main() 方法，访问 Student 类中的属性并赋值，打印出用户的信息。代码如下：

1. public class StudentTest {
2.     public static void main(String[] args) {
3.         // 创建Student类对象
4.         Student stu = new Student();
5.         // 向Student类对象中的属性赋值
6.         stu.name = "zhht";
7.  
8.         // stu.idNumber="043765290763137806";
9.         // 这是不允许的。提示stu.idNumber是不可见的，必须注释掉才可运行
10. 10.         stu.no = "20lil01637";
11. 11.         stu.email = "zhht@qq.com";
12. 12.         System.out.println(stu.info());
13. 13.     }

14. }

在 StudentTest 类中，“stu.idNumber="043765290763137806";”代码行将提示 “The field User.password is not visible”错误信息。将该代码行注释掉再运行 StudentTest.java 文件，输出的内容如下：

姓名：zhht，身份证号码：null，学号：20lil01637，邮箱：zhht@qq.com

在源文件中创建了两个类，分别为主类 StudentTest 和辅助类 Student，二者在同一个包中。
在辅助类 Student 中，创建了 4 个属性，其访问控制分别为默认的、私有的、受保护的和共有的，除了私有控制符修饰的变量之外，其他的都可以被主类访问，同时创建了一个共有的方法——info()，用于打印用户信息。
在主类 StudentTest 中，创建类 Student 的实例化对象 stu，通过对象 stu 来访问该对象中的属性并赋值，因为 idNumber 属性的修饰符为 private（私有的），因此，在 StudentTest 类中的 main() 方法中无法访问该属性。
从上面的例子中可以看出，范围控制修饰符成功地限制了访问者访问不同修饰符的属性（成员变量），从而实现了数据的隐藏。字段