Java 注释的三种形式
在 Java 中,注释主要分为三种:单行注释 //、多行注释 /* */ 以及文档注释 /** */。后两者虽然功能相似,但文档注释具有特殊用途,它是生成 API 文档的基础。
文档注释的语法
文档注释以 /** 开头,以 */ 结尾。与普通注释不同,它可以包含特定的标签(Tags),例如 @param、@return、@throws 等。这些标签会被 javadoc 工具识别,从而生成结构化的 HTML 文档。
下面是一个标准的示例:
/**
* 计算两个整数的和
* @param a 第一个加数
* @param b 第二个加数
* @return 两数之和
*/
public int add(int a, int b) {
return a + b;
}
为什么需要文档注释
很多开发者容易忽略这部分内容,觉得写代码就够了。但在实际项目中,清晰的文档能大幅降低沟通成本。当你使用 IDE 查看方法时,如果作者写了文档注释,鼠标悬停就能直接看到参数含义和返回值说明,这比阅读源码本身更直观。
此外,团队维护大型项目时,通过命令行运行 javadoc 命令,可以一键生成完整的在线帮助手册。这不仅是对代码的补充,也是对设计思路的一种沉淀。建议养成习惯,在定义公共接口时,顺手把文档注释写好。

