如何在Java创建自己的注释？

注释是代码中非常重要的一部分，它能够帮助程序员更好地理解、维护代码。Java 中的注释分为三种，分别是单行注释、多行注释和文档注释。其中，文档注释是最常用的一种注释，它可以用来生成 API 文档。

如何添加注释？

单行注释

单行注释是以 // 开头，后面跟着注释内容。单行注释可以出现在代码任何地方，但必须在代码行的末尾或者是单独一行。

// 这是一个单行注释
int a = 1; // 这也是一个单行注释

多行注释

多行注释是以 /* 开头，以 */ 结尾，这种注释可以包含一整个段落的注释。多行注释不能嵌套，但是可以使用多个多行注释来注释掉某一段代码。

/*
 * 这是一段多行注释
 * 它可以包含多个段落
 */

文档注释

文档注释是以 /** 开头，以 */ 结尾，这种注释要比其他注释更加详细，它可以用来生成 API 文档。文档注释中可以使用 HTML 标签来格式化注释内容，比如说 <code> 标签用来表示代码， <pre> 标签表示预格式化文本。

/**
 * 这是一段用来演示文档注释的代码
 * <pre>
 * int a = 1;
 * int b = 2;
 * int c = a + b;
 * </pre>
 */
public class Example {
}

如何编写好的文档注释？

编写好的文档注释应该包含以下几个方面：

注释的目的

注释的目的应该在前几句话中体现出来，这可以让代码的阅读者很快地分辨出这个类或者方法是用来做什么的。

/**
 * 这个类用来表示一个人的信息，包括姓名、性别、年龄等。
 */
public class Person {
}

参数

如果方法有参数，应该在文档注释中注明每个参数的类型和作用。

/**
 * 这个方法用来计算两个整数的和。
 * @param a 加数1
 * @param b 加数2
 * @return 两个参数的和
 */
public int sum(int a, int b) {
    return a + b;
}

返回值

如果方法有返回值，应该在文档注释中注明返回值的类型和意义。

/**
 * 这个方法用来计算两个整数的和。
 * @param a 加数1
 * @param b 加数2
 * @return 两个参数的和
 */
public int sum(int a, int b) {
    return a + b;
}

异常

如果方法可能会抛出异常，应该在文档注释中注明异常的类型和原因。

/**
 * 这个方法用来读取文件。
 * @param file 文件名
 * @return 文件的内容
 * @throws FileNotFoundException 文件不存在
 * @throws IOException 读取文件失败
 */
public String readFile(String file) throws FileNotFoundException, IOException {
    // 读取文件的代码
}

总结

注释在代码中起着非常重要的作用，它可以帮助我们更好地理解、维护代码。Java 中的三种注释分别是单行注释、多行注释和文档注释，其中文档注释是最常用的一种注释。编写好的文档注释应该包括注释的目的、参数、返回值、异常等信息，这可以帮助其他程序员更好地理解你的代码。