掌握单行、多行和文档注释的使用方法与最佳实践
在Java编程中，注释是一种重要的代码文档化手段。Java支持三种类型的注释，每种都有其特定的用途和语法。良好的注释习惯能够显著提高代码的可读性和可维护性。
Javadoc提供了丰富的标签来描述代码的各个方面，这些标签能够生成结构化的API文档。
| 标签 | 说明 | 使用示例 |
|---|---|---|
@author |
作者信息 | @author 张三 |
@version |
版本信息 | @version 1.0 |
@since |
起始版本 | @since JDK 1.8 |
@param |
参数说明 | @param name 用户姓名 |
@return |
返回值说明 | @return 用户对象 |
@throws |
异常说明 | @throws IllegalArgumentException |
@see |
参考链接 | @see String |
@deprecated |
已废弃标记 | @deprecated 使用newMethod()替代 |
/**
* Java注释示例程序
* 演示三种注释类型的使用方法
*
* 这是一个文档注释，用于生成API文档
* 通常用于类、方法和重要字段的说明
*
* @author Java学习者
* @version 1.0
* @since 2024-01-05
*/
public class CommentExample {
// 这是单行注释，用于简短的说明
// 通常用于解释代码的作用或注意事项
private String name;
/*
* 这是多行注释
* 可以跨越多行
* 适合较长的说明文字
* 或者临时注释掉一段代码
*/
private int age;
/**
* 构造方法 - 创建CommentExample对象
*
* @param name 姓名，不能为空
* @param age 年龄，必须大于0
*/
public CommentExample(String name, int age) {
this.name = name; // 设置姓名
this.age = age; // 设置年龄
}
/**
* 获取姓名
*
* @return 返回当前对象的姓名
*/
public String getName() {
return name;
}
/**
* 显示个人信息
*
* 这个方法会在控制台输出格式化的个人信息
* 包括姓名和年龄
*/
public void displayInfo() {
// 输出分隔线
System.out.println("=== 个人信息 ===");
// 输出姓名和年龄
System.out.println("姓名: " + name);
System.out.println("年龄: " + age + "岁");
/*
* 可以在这里添加更多信息
* 比如出生年份计算等
*/
}
}// 使用二分查找提高搜索效率
int index = binarySearch(array, target);
// 根据用户等级计算折扣：VIP用户享受8折优惠
double discount = user.isVip() ? 0.8 : 1.0;
/**
* 计算两个整数的和，处理溢出情况
*
* @param a 第一个加数
* @param b 第二个加数
* @return 两数之和
* @throws ArithmeticException 当计算结果溢出时
*/// 将i设置为0
int i = 0;
// 连接MySQL数据库（实际已改为PostgreSQL）
connection = getConnection();
// 开始
start();
单行注释（//）
多行注释（/* */）
文档注释（/** */）