[Java 基础]注释
注释在编程中扮演着非常重要的角色，它们是写给人类阅读的，而不是给计算机执行的。良好的注释可以极大地提高代码的可读性和可维护性。
为什么需要注释？
- 提高可读性： 注释可以解释代码的功能、实现思路、特殊处理等，帮助其他开发者（或者未来的你）更容易理解代码的意图
- 方便维护： 当代码需要修改或维护时，清晰的注释能够帮助开发者快速定位需要修改的部分，并理解修改可能带来的影响
- 生成文档： 特定格式的注释（Javadoc）可以被工具自动提取，生成专业的 API 文档
- 调试代码： 在调试过程中，可以使用注释临时禁用某些代码块，方便定位问题
- 作为备忘： 开发者可以在代码中添加一些临时的想法或注意事项
Java 支持三种类型的注释：
1. 单行注释 (Single-line Comments)
以双斜线 // 开头，直到行尾的内容都被视为注释。单行注释通常用于解释代码中的某一行或一小段代码的功能。
// 这是一个单行注释
int age = 30; // 声明一个整型变量 age 并赋值为 30
2. 多行注释 (Multi-line Comments)
以 /* 开头，以 / 结尾。/ 和 */ 之间的所有内容都被视为注释，可以跨越多行。多行注释通常用于解释一段较长的代码块、一个方法或一个类的整体功能。
/** 这是一个多行注释。* 它可以跨越多行，* 用于解释一段代码的功能或者提供更详细的说明。*/
public class MyClass {// ... 类的内容 ...
}
:::color3
多行注释不能嵌套使用。也就是说，在一个多行注释内部不能再包含另一个 /* ... */ 注释。
:::
3. 文档注释 (Documentation Comments) - Javadoc
文档注释是一种特殊的多行注释，以 /** 开头，以 */ 结尾。文档注释主要用于为类、接口、方法、构造器、字段和枚举常量生成 API 文档。Javadoc 工具可以解析这些注释，并生成 HTML 格式的文档。
文档注释的内容可以包含特殊的标签（以 @ 开头），用于描述不同的方面，例如参数、返回值、异常、作者、版本等。
/*** 这是一个表示一个简单计算器的类。* 它提供了加法和减法运算。** @author John Doe* @version 1.0* @since 1.0*/
public class Calculator {/*** 将两个整数相加。** @param a 第一个整数* @param b 第二个整数* @return 两个整数的和* @throws ArithmeticException 如果发生算术错误（虽然在这个例子中不会发生）*/public int add(int a, int b) {return a + b;}/*** 从第一个整数中减去第二个整数。** @param a 被减数* @param b 减数* @return 两个整数的差*/public int subtract(int a, int b) {return a - b;}
}
常用的 Javadoc 标签包括：
@author：标识作者。@version：标识版本号。@param：描述方法的参数，后面跟着参数名和描述。@return：描述方法的返回值。@throws或@exception：描述方法可能抛出的异常，后面跟着异常类名和描述。@since：标识从哪个版本开始引入。@deprecated：标识该元素已过时，并说明替代方案。
因为 IDEA 创建的 Java 类是没有类注释的，所以，我一般习惯在 IDEA 中创建一个类文档注释模板，让后配置对应的触发字符，输入触发字符就能快速的生成类的文档注释：
/***** @author jxd* {@code @date} $DATETIME$*/
date("yyyy/MM/dd HH:mm")
在已创建的类上使用 *head ，然后按下 Enter 键，就会自动生成文档注释模板。
编写良好注释的建议
- 保持注释的简洁和清晰： 注释应该易于理解，避免使用过于晦涩的术语或过长的段落。
- 注释应该准确地反映代码的功能： 当代码修改时，务必更新相关的注释，确保它们与代码保持一致。
- 解释代码的意图，而不是仅仅描述代码做了什么： 好的注释应该解释 为什么 这段代码是这样写的，而不是简单地重复代码本身。
- 为重要的代码块、方法和类添加注释： 特别是那些逻辑复杂、容易产生误解或者对外提供的 API。
- 使用文档注释 (Javadoc) 为公共 API 生成文档： 这有助于其他开发者了解如何使用你的代码。
- 避免过度注释： 对于显而易见的代码，不一定需要添加注释。过多的注释反而会使代码显得冗余。
- 使用统一的注释风格： 保持整个项目注释风格的一致性，提高代码的整体可读性。
- 及时删除不再需要的注释： 例如，一些临时的调试代码注释在问题解决后应该被删除。