Java注释是代码中用于解释说明的非执行内容，合理使用注释能够大幅提升代码的可读性和可维护性，对于团队协作和项目长期迭代有着重要意义。Java原生支持三种注释类型，不同注释的适用场景和添加位置存在差异，同时需要遵循相应的编写原则才能发挥注释的最大价值。
Java三种注释类型基础
Java的注释分为三类，语法和用途各有不同：
- 单行注释：以
//开头，仅对当前行内容生效，适合简短的说明。 - 多行注释：以
/*开头，*/结尾，可覆盖多行内容，适合较长的段落说明。 - 文档注释：以
/**开头，*/结尾，支持Javadoc工具生成API文档，适合类、方法、成员变量等对外暴露元素的说明。
注释的合理添加位置
类级别注释位置
文档注释应当添加在类定义的上方，用于说明类的核心功能、作者、版本、使用注意事项等信息。单行注释和多行注释一般不用于类级别说明，除非是临时的调试标记。
/**
* 用户实体类，封装用户的基础信息
* @author 开发者名称
* @version 1.0
*/
public class User {
// 类成员变量和方法
}
方法级别注释位置
方法的文档注释添加在方法定义上方，需要说明方法的功能、参数含义、返回值、可能抛出的异常。如果方法逻辑简单，也可以使用单行注释对关键逻辑进行补充说明。
/**
* 计算两个整数的和
* @param a 第一个加数
* @param b 第二个加数
* @return 两个加数的和
*/
public int add(int a, int b) {
// 直接返回相加结果
return a + b;
}
成员变量注释位置
类的成员变量的文档注释添加在变量定义上方，说明变量的含义和用途。如果是局部变量，仅在逻辑复杂时用单行注释说明即可，简单的局部变量不需要额外注释。
public class Order {
/**
* 订单编号，全局唯一
*/
private String orderId;
public void process() {
// 临时存储处理状态
int status = 0;
// 后续处理逻辑
}
}
代码块内部注释位置
代码块内部的注释主要使用单行注释，添加在需要说明的代码行的上方或者同一行末尾，用于解释复杂逻辑、特殊处理的原因、临时调试标记等。多行注释一般用于暂时注释掉大段不需要执行的代码。
public void checkPermission() {
// 校验用户是否登录
if (user == null) {
throw new RuntimeException("用户未登录");
}
int level = user.getLevel(); // 获取用户权限等级
/* 暂时注释掉高级权限校验逻辑
if (level < 5) {
throw new RuntimeException("权限不足");
}
*/
}
注释编写的核心原则
必要性原则
注释不是越多越好，仅对复杂逻辑、特殊处理、对外暴露的接口添加注释，简单易懂的代码不需要冗余注释。比如int sum = a + b;这样的代码就不需要额外添加注释说明是求和。
准确性原则
注释内容必须和代码逻辑保持一致，当代码修改时，对应的注释也要同步更新，避免出现注释和代码不符的情况，否则会误导后续维护的开发者。
简洁性原则
注释内容要简洁明了，直接说明核心信息，不要添加无关的冗余内容，也不要在注释中写大段的业务逻辑描述，避免注释比代码还长。
规范性原则
文档注释要遵循Javadoc的规范，合理使用@param、@return、@throws等标签，方便后续生成标准的API文档。团队内部可以统一注释的格式要求，保持整体风格一致。
常见注释误区
- 不要为了凑注释而写无意义的注释，比如
// 给a赋值这种说明代码本身就表达的内容。 - 不要用注释包裹大段废弃的代码，废弃代码应当直接删除，通过版本控制工具可以找回历史版本。
- 不要在注释中写和代码无关的内容，比如个人心情、无关的吐槽等。