Java注释详解：单行、多行与文档注释的区别与应用
目录
背景：
一、Java注释的三种类型
1. 单行注释
2. 多行注释
3. 文档注释
二、三种注释的深度对比
三、注释的最佳实践
四、高级应用技巧
1. 文档注释中的HTML标签
2. 常用Javadoc标签
3. 生成API文档
五、注释的陷阱与注意事项
六、实际案例解析
1. Spring框架中的注释示例
2. JDK源码中的注释示例
结语
背景：
作为Java开发者，注释是我们日常编码中不可或缺的部分。本文将深入探讨Java中的三种注释方式：单行注释、多行注释和文档注释，分析它们的区别、适用场景以及最佳实践。
一、Java注释的三种类型
1. 单行注释
单行注释以//开头，只对当前行有效：
// 这是一个单行注释
int age = 25; // 这里也可以添加单行注释特点：
- 简洁明了，适合简短说明
- 只影响注释符号到行尾的内容
- 编译时会被完全忽略
2. 多行注释
多行注释以/*开头，以*/结尾：
/** 这是一个多行注释* 可以跨越多行* 常用于方法内部的复杂逻辑说明*/特点：
- 可以跨越多行
- 适合较长的说明或临时注释代码块
- 编译时会被完全忽略
- 不能嵌套使用
3. 文档注释
文档注释以/**开头，以*/结尾：
/*** 计算两个数的和* @param a 第一个加数* @param b 第二个加数* @return 两个数的和*/
public int add(int a, int b) {return a + b;
}特点：
- 专门用于生成API文档
- 支持HTML标签和Javadoc标签（如@param, @return等）
- 可以通过javadoc工具生成HTML文档
- 是Java官方推荐的API文档方式
二、三种注释的深度对比
| 特性 | 单行注释 | 多行注释 | 文档注释 |
|---|---|---|---|
| 语法 | // | /* ... */ | /** ... */ |
| 跨行能力 | 否 | 是 | 是 |
| 文档生成 | 不支持 | 不支持 | 支持 |
| 特殊标签 | 无 | 无 | @param, @return等 |
| 编译处理 | 忽略 | 忽略 | 可提取为文档 |
| 典型用途 | 简短说明 | 代码块说明/临时注释 | API文档 |
三、注释的最佳实践
-
单行注释：
- 用于方法内部的简短说明
- 解释复杂或非直观的代码逻辑
- 临时禁用单行代码
-
多行注释：
- 方法内部的较长说明
- 临时注释掉代码块（但版本控制工具更适合此用途）
- 不适合长期存在的注释，应考虑重构代码使其更清晰
-
文档注释：
- 所有public类和public/protected方法都应该有文档注释
- 包含方法功能、参数说明、返回值、异常等信息
- 使用标准Javadoc标签
- 保持与代码同步更新
四、高级应用技巧
1. 文档注释中的HTML标签
/*** <p>这是一个段落</p>* <ul>* <li>列表项1</li>* <li>列表项2</li>* </ul>*/2. 常用Javadoc标签
@param：方法参数说明@return：返回值说明@throws/@exception：抛出异常说明@see：引用其他类或方法@deprecated：标记为已弃用@since：指明引入版本
3. 生成API文档
使用javadoc工具生成HTML文档：
javadoc -d doc -author -version MyClass.java五、注释的陷阱与注意事项
-
注释不能替代清晰的代码：好的代码应该自解释，注释只应解释"为什么"而不是"做什么"
-
避免过度注释：如
i++; // i增加1这样的注释毫无意义 -
及时更新注释：过时的注释比没有注释更糟糕
-
多行注释不能嵌套：
/* /* 嵌套 */ */会导致编译错误 -
特殊字符处理：文档注释中的HTML特殊字符需要转义
六、实际案例解析
1. Spring框架中的注释示例
/*** Interface defining methods for accessing a message source.* Provides support for parameterization and internationalization.* * @author Juergen Hoeller* @since 1.6* @see org.springframework.context.MessageSourceResolvable*/
public interface MessageSource {// ...
}2. JDK源码中的注释示例
// HashMap.java中的单行注释示例
if (oldThr > 0) // initial capacity was placed in thresholdnewCap = oldThr;结语
合理使用三种注释是Java开发者的基本功。记住：单行注释用于简短说明，多行注释用于代码块说明或临时注释，文档注释用于API说明。良好的注释习惯不仅能提高代码可维护性，还能通过Javadoc生成专业的API文档，是团队协作的重要保障。
希望本文能帮助你更好地理解和使用Java注释。如果你有任何问题或建议，欢迎在评论区留言讨论。