174. Java 注释 - 声明注释类型
🎯 注释替代代码中的文档信息
在传统的 Java 编程实践中，团队可能会在每个类的开头插入详细的注释，用以提供关于类的元数据（如作者、修改日期、版本等）。这种方式虽然有效，但随着项目变得越来越复杂，可能会导致冗长和重复的注释，尤其是当多个类共享类似的信息时。
例如，以下是一个传统的注释方式：
public class Generation3List extends Generation2List {
// Author: John Doe
// Date: 3/17/2002
// Current revision: 6
// Last modified: 4/12/2004
// By: Jane Doe
// Reviewers: Alice, Bill, Cindy
// class code goes here
}
📝 定义自定义注释类型
为了使代码更加简洁和结构化，可以使用自定义注释类型来替代这些繁琐的注释信息。定义自定义注释类型需要使用 @interface 关键字，它的语法类似于接口定义，但用于定义注释类型。注释类型的元素就像方法一样，可以定义返回类型和默认值。
下面是一个自定义注释类型的定义示例，用于替代上面的类级注释：
@interface ClassPreamble {
String author(); // 作者
String date(); // 日期
int currentRevision() default 1; // 当前版本，默认值为1
String lastModified() default "N/A"; // 最后修改日期，默认值为 "N/A"
String lastModifiedBy() default "N/A"; // 最后修改人，默认值为 "N/A"
String[] reviewers(); // 审阅者，注意使用数组
}
🎯 注释元素说明
- 元素声明： 自定义注释的元素类似于方法声明。每个元素都有一个返回类型（如
String、int或数组类型）。有些元素可以提供默认值，如果不提供，使用默认值。 - 数组： 在注释中，可以使用数组类型（如
String[]）来存储多个值。例如，reviewers数组可以包含多个审阅者。
📝 使用自定义注释
一旦定义了注释类型，就可以在代码中使用它，并为注释的元素提供具体的值。以下是如何在类声明中使用 @ClassPreamble 注释的示例：
@ClassPreamble(
author = "John Doe",
date = "3/17/2002",
currentRevision = 6,
lastModified = "4/12/2004",
lastModifiedBy = "Jane Doe",
reviewers = {"Alice", "Bob", "Cindy"}
)
public class Generation3List extends Generation2List {
// class code goes here
}
📌 注释文档化
为了确保自定义注释在 Javadoc 生成的文档中能够显示，必须使用 @Documented 注释对注释类型进行标记。这使得 Javadoc 工具能够识别和处理该注释，生成包含相关信息的文档。
import java.lang.annotation.*;
@Documented
@interface ClassPreamble {
String author();
String date();
int currentRevision() default 1;
String lastModified() default "N/A";
String lastModifiedBy() default "N/A";
String[] reviewers();
}
🎯 @Documented 注释的作用
- @Documented： 这是一个元注释（
meta-annotation），它会告知Javadoc工具在生成文档时包括此注释的相关信息。没有@Documented，自定义注释不会出现在Javadoc文档中。
📝 总结
- 自定义注释类型 可以替代传统的类头部注释，使代码更加结构化和可维护。
- 通过
@interface语法定义注释类型，并可以为注释类型元素指定默认值。 - 在使用自定义注释时，为每个元素提供实际的值，使其能更好地传达元数据。
- 使用
@Documented注释确保自定义注释会出现在Javadoc文档中，提升文档的可读性。
