下面我将从 Java 注释类型 和 Eclipse 中的快捷操作 两个方面为你详细讲解。
（图片来源网络，侵删）
Java 注释类型
Java 提供了三种类型的注释,每种都有其特定的用途。
单行注释
这是最常用、最简单的注释方式，以双斜杠 开头,直到该行末尾的所有内容都会被编译器忽略。
用途：
- 解释某一行代码的作用。
- 在代码行后进行简短的说明。
示例：
（图片来源网络，侵删）
// 这是一个单行注释，用于解释下面这行代码
int age = 25; // 定义一个整型变量 age 并赋值为 25
// 临时屏蔽一行代码进行调试
// System.out.println("这行代码暂时不执行");
多行注释
也称为块注释，以 开始，以 结束，它们之间的所有内容都会被编译器忽略,可以跨越多行。
用途：
- 对一段代码块或一个方法进行详细的说明。
- 在调试时临时屏蔽多行代码。
示例：
/*
* 这是一个多行注释。
* 它可以跨越多行，
* 通常用于对复杂的代码逻辑进行说明。
*/
public void calculateArea() {
// ... 计算面积的代码
}
文档注释
这是 Java 中最强大、最规范的注释类型，它以 开始，以 结束，它不仅能被编译器忽略，还能被 JDK 提供的工具 Javadoc 解析，生成格式化的 HTML 文档。
用途：
- 为类、方法、字段等生成 API 文档。
- 提供关于代码的正式、规范化的描述。
Javadoc 标签： 文档注释中常用一些特殊的标签（以 开头）来提供结构化信息：
| 描述 | 示例 | |
|---|---|---|
@author |
标识作者 | @author Your Name |
@version |
标识版本号 | @version 1.0 |
@param |
描述方法的参数 | @param name 参数名，表示用户姓名 |
@return |
描述方法的返回值 | @return 返回用户的年龄 |
@throws |
描述方法可能抛出的异常 | @throws IllegalArgumentException 如果年龄为负数 |
@see |
引用其他相关内容 | @see AnotherClass |
@deprecated |
标记该方法或类已过时，不推荐使用 | @deprecated 请使用 newMethod() 代替 |
示例：
/**
* 用户类，用于存储和操作用户信息。
* 这个类提供了基本的用户数据管理功能。
*
* @author John Doe
* @version 1.1
* @since 1.0
*/
public class User {
private String name;
private int age;
/**
* 构造函数，用于创建一个新的用户对象。
*
* @param name 用户名，不能为 null 或空字符串
* @param age 用户年龄，必须大于 0
* @throws IllegalArgumentException name 或 age 不合法
*/
public User(String name, int age) {
if (name == null || name.isEmpty()) {
throw new IllegalArgumentException("用户名不能为空");
}
if (age <= 0) {
throw new IllegalArgumentException("年龄必须大于 0");
}
this.name = name;
this.age = age;
}
/**
* 获取用户的年龄。
*
* @return 用户的年龄
*/
public int getAge() {
return this.age;
}
/**
* 设置用户的年龄。
* 这是一个已过时的方法，因为它没有进行参数验证。
*
* @param age 新的年龄
* @deprecated 请使用 setAgeWithValidation(int age) 代替
*/
@Deprecated
public void setAge(int age) {
this.age = age;
}
}
Eclipse 中的快捷操作和辅助功能
Eclipse 作为强大的 IDE,为注释提供了非常便捷的快捷键和自动化功能。
快捷键
| 功能 | Windows/Linux 快捷键 | macOS 快捷键 |
|---|---|---|
| 添加/取消单行注释 | Ctrl + / |
Cmd + / |
| 添加/取消多行注释 | Ctrl + Shift + / |
Cmd + Shift + / |
| 生成 Javadoc 注释 | Alt + Shift + J |
Cmd + Alt + J |
| 快速定位到注释 | Ctrl + Shift + G (查找引用) 也可用于定位注释，但更常用的是 Ctrl + O (大纲) 或 Ctrl + T (类型层次) |
与 Windows/Linux 相同 |
自动生成 Javadoc 注释
这是 Eclipse 最实用的功能之一，当你编写完一个方法或类的结构后，只需按下 Alt + Shift + J，Eclipse 就会自动为你生成一个标准的 Javadoc 模板。
操作演示：
-
写一个方法签名：
public void processOrder(String orderId, double amount) { } -
将光标放在方法签名行内。
-
按下
Alt + Shift + J。 -
Eclipse 会自动填充模板：
/** * * * @param orderId * @param amount */ public void processOrder(String orderId, double amount) { } -
你只需在 之间填写描述，并完善
@param的说明即可。
代码格式化与注释对齐
当你有多行注释时，为了让它们对齐美观,可以使用代码格式化功能。
- 快捷键:
Ctrl + Shift + F(Windows/Linux) 或Cmd + Shift + F(macOS) - 操作: 选中需要格式化的代码，然后按下快捷键，Eclipse 会自动调整缩进和对齐,包括注释。
格式化前:
int a = 1; // a is one
String b = "hello"; // b is a string
double c = 3.14; // c is pi
格式化后:
int a = 1; // a is one String b = "hello"; // b is a string double c = 3.14; // c is pi
注释模板
你可以自定义注释的模板，在创建新类时自动生成 @author 和 @version 等信息。
- 打开
Window->Preferences(在 macOS 上是Eclipse->Preferences)。 - 导航到
Java->Code Style->Code Templates。 - 在右侧的列表中，选择
Comments。 - 你可以在这里修改各种类型的模板，
Files(新文件头)、Types(类)、Fields(字段)、Methods(方法) 等。 - 修改后点击
Apply和OK。
你可以修改 Files 模板,使其包含你的姓名和邮箱：
/**
* @author ${user}
* @version ${date}
*/
导出 Javadoc 文档
当你写好了带有文档注释的代码后，可以直接在 Eclipse 中生成 HTML 文档。
- 在 Package Explorer 中,右键点击你的项目。
- 选择
Export。 - 在弹出的窗口中，展开
Java文件夹，选择Javadoc，然后点击Next。 - 选择你要生成文档的项目、输出目录，并可以配置一些 Javadoc 的参数。
- 点击
Finish，Eclipse 就会为你生成一个包含所有 注释的网站。
| 注释类型 | 符号 | 主要用途 | Eclipse 快捷键 |
|---|---|---|---|
| 单行注释 | 行内解释、临时屏蔽 | Ctrl + / |
|
| 多行注释 | 多行解释、临时屏蔽 | Ctrl + Shift + / |
|
| 文档注释 | 生成正式 API 文档 | Alt + Shift + J |
最佳实践：
- 代码应该是自解释的：尽量写出清晰、有意义的变量名和方法名，注释是辅助,而不是替代。
- 解释“为什么”，而不是“是什么”：代码本身说明了它做了什么（What），而注释应该解释你为什么要这么做（Why）,特别是对于那些不直观的算法或业务逻辑。
- 保持注释的更新：当代码逻辑改变时，一定要同步更新相关的注释,否则过时的注释比没有注释更具有误导性。
- 使用文档注释：对于任何可能被外部调用的公共 API（类、方法）,都应该使用文档注释。
希望这份详细的指南能帮助你更好地在 Java 和 Eclipse 中使用注释！
