Java 注释的三种类型
Java 主要有三种注释,它们的作用和用途各不相同。
（图片来源网络，侵删）
单行注释
以双斜杠 开头,直到该行末尾结束。
- 用途：用于解释某一行代码或一小段代码的功能，通常用于临时的、短小的说明。
- 示例：
public class HelloWorld { public static void main(String[] args) { // 这是一个简单的打印语句 System.out.println("Hello, World!"); } }
多行注释
以 开始，以 结束,可以跨越多行。
-
用途：用于对一段代码块进行详细的说明，或者用于暂时禁用一大段代码（调试时常用）。
-
示例：
（图片来源网络，侵删）public class Calculator { public int add(int a, int b) { /* * 这是一个加法方法。 * 它接收两个整数作为参数， * 然后返回它们的和。 */ return a + b; } public void oldMethod() { // 下面这段代码是旧版本的实现，现在不再使用 /* int result = 0; for (int i = 0; i < 10; i++) { result += i; } System.out.println(result); */ } }
文档注释 (Javadoc 注释)
以 开始，以 结束，它是多行注释的一种特殊形式，专门用于生成 API 文档。
-
用途：为类、方法、字段等提供标准的文档说明，这些注释可以被
javadoc工具解析，生成格式化的 HTML 文档。 -
核心元素：
@param: 描述方法的参数。@return: 描述方法的返回值。@throws/@exception: 描述方法可能抛出的异常。@see: 引用其他相关内容。@deprecated: 标记该方法或类已过时。
-
示例：
/** * 这个类演示了如何使用 Javadoc 注释。 * @author YourName * @version 1.0 */ public class DocumentedExample { /** * 计算两个整数的和。 * * @param a 第一个整数 * @param b 第二个整数 * @return 两个参数的和 * @throws IllegalArgumentException 如果任一参数为负数 */ public int sum(int a, int b) { if (a < 0 || b < 0) { throw new IllegalArgumentException("参数不能为负数"); } return a + b; } }
在 Eclipse 中高效使用注释
Eclipse 为注释操作提供了许多快捷键和便捷功能,能极大提升你的编码效率。
快捷键
-
添加/取消单行注释
- Windows/Linux:
Ctrl + / - macOS:
Cmd + / - 效果：将光标所在的行（或选中的多行）用 注释掉，如果已经是注释，则取消注释,这是最常用的快捷键。
- Windows/Linux:
-
添加/取消多行注释
- Windows/Linux:
Ctrl + Shift + / - macOS:
Cmd + Shift + / - 效果：将选中的代码块用 包裹起来，如果选中部分已经是多行注释,则取消。
- Windows/Linux:
-
添加 Javadoc 注释
- Windows/Linux:
Alt + Shift + J - macOS:
Cmd + Shift + J - 效果：将光标放在类、方法或字段上，按下此快捷键，Eclipse 会自动生成标准的 Javadoc 模板,你只需填写描述即可。
- Windows/Linux:
自动生成 Javadoc 文档
当你写好了 Javadoc 注释后，可以使用 Eclipse 的功能来生成 HTML 文档。
-
配置文档生成:
- 右键点击你的项目 -> Export (导出)。
- 在弹出的窗口中，展开 Java 文件夹，选择 Javadoc -> Next。
- 在 Javadoc command 中，确保指向了你的 JDK 安装目录下的
javadoc.exe(Windows) 或javadoc(macOS/Linux)。 - 在 Destination 中,选择一个文件夹来存放生成的文档。
- 在 Select types to export 中,选择你想要生成文档的包或类。
- 点击 Finish。
-
直接在 Eclipse 中预览:
- 将光标放在你带有 Javadoc 注释的方法或类上。
- 按
F2键，或者使用快捷键Ctrl + Shift + P(Windows/Linux) /Cmd + Shift + P(macOS)。 - Eclipse 会在一个小窗口中显示该元素的 Javadoc 内容,非常方便。
代码模板
Eclipse 允许你自定义代码模板，让你输入缩写就能快速生成一段代码结构,其中就包括注释模板。
-
打开模板设置:
- 菜单栏: Window -> Preferences -> Java -> Editor -> Templates (Windows/Linux)
- 菜单栏: Eclipse -> Preferences -> Java -> Editor -> Templates (macOS)
-
示例:
- 你可以新建一个模板，
fori如下：// Enhanced for loop for (${iterable_type} ${iterable_element} : ${iterable}) { ${cursor} } - 之后，你在代码中输入
fori，然后按Ctrl + Space(代码补全快捷键)，Eclipse 就会帮你展开这个模板。
- 你可以新建一个模板，
格式化注释
Eclipse 可以自动格式化你的注释,使其保持统一的风格。
- 快捷键:
- Windows/Linux:
Ctrl + Shift + F - macOS:
Cmd + Shift + F
- Windows/Linux:
- 效果：它会调整注释的对齐方式、换行等,使其符合项目的代码风格。
最佳实践
-
注释解释“为什么”，而不是“是什么”。
- 坏注释:
// 创建一个字符串变量String name = "John Doe"; // 创建一个字符串变量
- 好注释:
// 使用用户名作为唯一的会话标识符String sessionId = generateSessionId(); // 使用用户名作为唯一的会话标识符
- 坏注释:
-
保持注释的更新，代码修改后，相关的注释也必须同步修改，否则会产生误导,过时的注释比没有注释更糟糕。
-
避免冗余和显而易见的注释。
- 坏注释:
// 循环10次 for (int i = 0; i < 10; i++) { // 打印 i System.out.println(i); }
- 坏注释:
-
为复杂的算法或业务逻辑添加注释，当代码的逻辑不是一目了然时,清晰的注释是必要的。
-
优先使用有意义的变量和方法名，好的命名本身就是一种自解释的文档,可以减少对注释的依赖。
| 功能 | 操作方式 | 快捷键 (Windows/Linux) | 快捷键 (macOS) |
|---|---|---|---|
| 单行注释/取消 | 选中行或代码块 | Ctrl + / |
Cmd + / |
| 多行注释/取消 | 选中代码块 | Ctrl + Shift + / |
Cmd + Shift + / |
| 生成 Javadoc | 光标在方法/类上 | Alt + Shift + J |
Cmd + Shift + J |
| 预览 Javadoc | 光标在方法/类上 | F2 或 Ctrl + Shift + P |
F2 或 Cmd + Shift + P |
| 格式化代码 | 整个文件或选中区域 | Ctrl + Shift + F |
Cmd + Shift + F |
熟练掌握这些注释技巧和 Eclipse 功能，能让你的代码更加清晰、专业,并且易于维护。
