注释是编程中不可或缺的部分，它不仅能提高代码的可读性，还能为开发者提供重要信息。本文将详细介绍Java中的各种注释方式，包括单行注释、多行注释、文档注释，以及注释的最佳实践和高级用法。
一、Java注释基础
1.1 单行注释
单行注释以//开头，直到行尾的所有内容都被视为注释。
javapublic class BasicComments {
public static void main(String[] args) {
// 这是一个单行注释
System.out.println("Hello, World!"); // 也可以放在代码行尾
int x = 10; // 变量x的初始化值
}
}1.2 多行注释
多行注释以/*开头，以*/结尾，可以跨越多行。
javapublic class MultiLineComments {
public static void main(String[] args) {
/*
* 这是一个多行注释
* 可以跨越多行
* 常用于较长的说明或临时禁用代码块
*/
System.out.println("Multi-line comments example");
/*
int a = 5;
int b = 10;
System.out.println(a + b); // 这段代码被注释掉了
*/
}
}二、Java文档注释（Javadoc）
Javadoc是Java特有的文档生成工具，可以从源代码中提取注释生成HTML文档。
2.1 基本Javadoc语法
Javadoc注释以/**开头，以*/结尾，通常放在类、方法或字段声明之前。
java/**
* 表示一个简单的计算器类
* @author John Doe
* @version 1.0
*/
public class Calculator {
/**
* 存储计算结果的字段
*/
private double result;
/**
* 将两个数相加
* @param a 第一个加数
* @param b 第二个加数
* @return 两个数的和
*/
public double add(double a, double b) {
result = a + b;
return result;
}
}2.2 常用Javadoc标签
标签 | 用途 | 示例 |
| 标识类的作者 |
|
| 标识类的版本 |
|
| 描述方法参数 |
|
| 描述返回值 |
|
| 描述方法可能抛出的异常 |
|
| 创建指向其他文档的链接 |
|
| 标识引入该成员的版本 |
|
| 标记已过时的方法或类 |
|
2.3 完整Javadoc示例
java/**
* 学生成绩管理系统核心类
* <p>
* 提供学生成绩的添加、查询、统计等功能
* </p>
* @author Alice Smith
* @version 2.1
* @since 2023-01-01
*/
public class GradeManager {
private Map<String, Double> studentGrades;
/**
* 构造函数初始化成绩映射
*/
public GradeManager() {
studentGrades = new HashMap<>();
}
/**
* 添加学生成绩
* @param studentId 学生ID，不能为空
* @param grade 成绩，必须在0-100之间
* @throws IllegalArgumentException 如果参数无效
* @see #getGrade(String)
*/
public void addGrade(String studentId, double grade)
throws IllegalArgumentException {
if (studentId == null || studentId.trim().isEmpty()) {
throw new IllegalArgumentException("学生ID不能为空");
}
if (grade < 0 || grade > 100) {
throw new IllegalArgumentException("成绩必须在0-100之间");
}
studentGrades.put(studentId, grade);
}
/**
* 获取学生成绩
* @param studentId 学生ID
* @return 对应的学生成绩，如果不存在返回null
* @since 1.2 新增方法
*/
public Double getGrade(String studentId) {
return studentGrades.get(studentId);
}
/**
* 计算班级平均分
* @return 班级平均分
* @deprecated 从2.0版本开始使用{@link #calculateAverage(boolean)}代替
*/
@Deprecated
public double calculateAverage() {
return calculateAverage(false);
}
/**
* 计算班级平均分
* @param includeAbsent 是否包括缺考学生(成绩为0)
* @return 班级平均分
*/
public double calculateAverage(boolean includeAbsent) {
// 实现代码...
return 0.0;
}
}三、注释的最佳实践
3.1 类注释规范
java/**
* 类名称：订单处理器
* 类描述：处理订单创建、支付和状态更新等业务逻辑
* 创建时间：2023-05-15
* 修改记录：
* 2023-06-10 添加了支付超时处理功能 (张三)
* 2023-07-22 优化了订单状态转换逻辑 (李四)
*/
public class OrderProcessor {
// 类实现...
}3.2 方法注释规范
java/**
* 验证用户登录信息
* @param username 用户名，不能为null且长度在4-20个字符之间
* @param password 密码，不能为null且长度至少为6个字符
* @return 验证结果：true表示验证通过，false表示验证失败
* @throws ValidationException 如果用户名或密码格式无效
* @example
* <pre>
* try {
* boolean isValid = authService.validateLogin("user123", "password123");
* if (isValid) {
* // 登录成功处理
* }
* } catch (ValidationException e) {
* // 处理验证异常
* }
* </pre>
*/
public boolean validateLogin(String username, String password)
throws ValidationException {
// 方法实现...
}3.3 复杂算法注释示例
java/**
* 快速排序算法实现
* <p>
* 算法思想：
* 1. 从数列中挑出一个元素，称为"基准"(pivot)
* 2. 重新排序数列，所有比基准值小的元素摆放在基准前面，
* 所有比基准值大的元素摆在基准后面(相同的数可以到任一边)。
* 在这个分区结束之后，该基准就处于数列的中间位置。
* 3. 递归地把小于基准值元素的子数列和大于基准值元素的子数列排序
* </p>
* @param arr 待排序数组
* @param low 起始索引
* @param high 结束索引
*/
public void quickSort(int[] arr, int low, int high) {
if (low < high) {
// 找到分区点
int pi = partition(arr, low, high);
// 递归排序分区
quickSort(arr, low, pi - 1);
quickSort(arr, pi + 1, high);
}
}
/**
* 分区操作辅助方法
* @return 返回分区点的索引
*/
private int partition(int[] arr, int low, int high) {
int pivot = arr[high]; // 选择最后一个元素作为基准
int i = low - 1; // 小于基准的元素的索引
for (int j = low; j < high; j++) {
// 如果当前元素小于或等于基准
if (arr[j] <= pivot) {
i++;
// 交换arr[i]和arr[j]
swap(arr, i, j);
}
}
// 交换arr[i+1]和基准(arr[high])
swap(arr, i + 1, high);
return i + 1;
}
/**
* 交换数组中两个元素的位置
*/
private void swap(int[] arr, int i, int j) {
int temp = arr[i];
arr[i] = arr[j];
arr[j] = temp;
}四、高级注释技巧
4.1 使用{@code}标签保留代码格式
java/**
* 使用示例：
* <pre>
* String result = {@code StringUtil.capitalize("hello")};
* // 结果为 "Hello"
* </pre>
*/
public class StringUtil {
public static String capitalize(String str) {
if (str == null || str.isEmpty()) {
return str;
}
return str.substring(0, 1).toUpperCase() + str.substring(1).toLowerCase();
}
}4.2 使用{@link}创建内部链接
java/**
* 用户服务类，提供用户管理相关功能
* @see com.example.service.UserAuthService 用户认证服务
* @see com.example.dao.UserRepository 用户数据访问层
*/
public class UserService {
// 类实现...
}
/**
* 用户认证服务
* @see UserService#authenticate(String, String) 认证方法
*/
public class UserAuthService {
// 类实现...
}4.3 使用<pre>标签保留格式化文本
java/**
* 配置示例：
* <pre>
* {
* "database": {
* "url": "jdbc:mysql://localhost:3306/mydb",
* "username": "admin",
* "password": "secret"
* },
* "cache": {
* "enabled": true,
* "ttl": 3600
* }
* }
* </pre>
*/
public class AppConfig {
// 类实现...
}五、生成Javadoc文档
5.1 使用命令行生成
bash# 在项目根目录执行
javadoc -d docs -author -version -windowtitle "My Project API" src/*.java5.2 使用Maven生成
在pom.xml中添加插件配置：
xml<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>3.3.2</version>
<configuration>
<show>private</show>
<nohelp>true</nohelp>
<doclint>none</doclint>
</configuration>
<executions>
<execution>
<id>generate-javadoc</id>
<phase>package</phase>
<goals>
<goal>javadoc</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>然后运行：
bashmvn javadoc:javadoc5.3 使用IntelliJ IDEA生成
- 右键点击项目或包
- 选择 "Tools" > "Generate JavaDoc..."
- 配置输出目录和其他选项
- 点击 "OK" 生成文档
六、注释的注意事项
- 不要过度注释：好的代码应该自解释，注释应补充代码无法表达的信息
- 保持注释更新：代码修改时，相关注释也应同步更新
- 避免无意义的注释：
java// 不好的注释
int i = 0; // 将i初始化为0
// 好的注释
int retryCount = 0; // 重试次数计数器- 对复杂逻辑必须注释：特别是算法、优化技巧或特殊处理
- 使用英文注释：特别是开源项目或团队协作时
七、总结
- 三种注释类型：
- 单行注释：
// - 多行注释：
/* ... */ - 文档注释：
/** ... */(用于Javadoc)
- Javadoc核心标签：
@param,@return,@throws,@see,@since,@deprecated
- 最佳实践：
- 为所有公共类和方法编写Javadoc
- 保持注释简洁准确
- 使用高级标签增强文档可读性
- 定期审查和更新注释
通过合理使用注释，你可以创建出不仅功能完善而且易于理解和维护的Java代码。记住，好的注释是优秀代码的重要组成部分！
