Java注释分三种：单行（//）、多行（/.../）和文档注释（/.../）；//用于简短说明或禁用代码，/.../用于跨行说明或屏蔽代码段，/.../生成Javadoc并支持@param等标签。
Java注释用 // 写单行，用 /* ... */ 写多行，文档注释用 /** ... */ 生成API说明。
单行注释：用两个斜杠（//）
从 // 开始到行末的所有内容都会被编译器忽略。适合简短说明、临时禁用某行代码或标注小逻辑。
- 写在代码上方或同行末尾均可，但建议保持对齐、不挤占可读性
- 避免过度使用，比如每行都加无意义的注释（如 // i++）
- 示例：
// 计算用户积分，按登录天数累加
int score = days * 10;
int bonus = (isVip ? 50 : 0); // VIP用户额外奖励
多行注释：用 /* ... */ 包裹
适用于跨多行的说明、暂时屏蔽一段代码，或写较详细的内部说明。
- 不能嵌套，即 /* ... /* ... */ ... */ 是非法的
- 注意缩进和换行，避免把关键代码意外包进注释里
- 示例：
/*
初始化配置参数：
- timeout：连接超时毫秒数
- retries：失败重试次数
*/
config.setTimeout(5000);
文档注释：用 /** ... */ 生成Javadoc
这是专为生成API文档设计的注释，必须放在类、方法、字段等声明之前，支持特定标签（如 @param、@return、@throws）。
立即学习“Java免费学习笔记（深入）”；
- 每个 public 类/方法/字段建议配文档注释，尤其对外提供接口时
- 常用标签：
@param name 描述参数含义
@return 描述返回值
@throws ExceptionName 说明可能抛出的异常 - 示例：
/**
* 根据用户ID查询完整信息
* @param userId 用户唯一标识，不能为空
* @return User对象，查不到返回null
* @throws IllegalArgumentException 当userId为null或空字符串时抛出
*/
public User findUserById(String userId) { ... }
实用建议与避坑点
- 注释要随代码更新，过时注释比没注释更误导人
- 别用注释代替清晰命名（例如不用写 // i是循环变量，而应写 for (int index : list)）
- 禁止用注释“掩盖”坏代码（如大段被注释掉的旧逻辑），该重构就重构
- 团队中可约定注释风格（如是否在 // 后加空格、多行注释是否用星号对齐），提升一致性
