<p>Java注释规范核心是“写得准、用得上、生成得了”，必须用/* /文档注释在类/接口/枚举、public/protected方法、public字段三处，配合@param/@return/@throws等标签，禁用//和/ /替代Javadoc，辅以package-info.java和自动化检查保障质量。</p>
Java 基础中的注释规范，核心目标不是“写得多”，而是“写得准、用得上、生成得了”。高质量文档（如 Javadoc HTML）依赖的是结构化、语义明确的文档注释，而非随意添加的说明文字。
必须用 /** */ 文档注释的三类位置
只有在这些位置使用标准 Javadoc 注释，才能被 javadoc 工具识别并生成可导航的 API 文档：
-
类/接口/枚举声明上方：说明整体职责、设计意图、典型用法。例如：
/**
* 用户管理服务，封装用户注册、登录、权限校验等核心流程。
* 支持 JWT 认证与本地密码加密存储。
* @since 1.2
* @author liwei
*/
public class UserService { ... } - public 或 protected 方法声明上方：必须包含 @param（每个参数）、@return（非 void 方法）、@throws（显式抛出的异常）。参数名和描述要一一对应，不遗漏、不冗余。
-
public 字段（含常量）声明上方：解释字段用途、取值范围、线程安全性等关键约束。例如：
/**
* 默认超时时间，单位毫秒。生产环境建议设为 5000，避免长阻塞。
* @see #setTimeout(int)
*/
public static final int DEFAULT_TIMEOUT = 3000;
别用错注释类型：什么场景用什么符号
混淆注释类型会导致文档丢失或 IDE 提示失效：
Alibabacloud Sdk Client Initialization For Java
下载
在 Java 中初始化和管理阿里云 SDK客户端。包括单例模式、线程安全、endpoint 与 region 配置、VPC 终端节点、同步与异步等。
-
// 单行注释：只用于临时说明、调试标记、或极简上下文（如
int retryCount = 0; // 重试次数，最大3次）。不能替代 Javadoc。 - /* ... */ 多行注释：仅用于临时禁用代码块，或在源码中写大段说明性文字（如算法原理摘要），但不会出现在生成的文档中。
-
/** ... */ 文档注释：唯一能被 javadoc 工具提取的格式。IDE（如 IntelliJ）在输入
/**后按 Enter 会自动补全 @param/@return 框架，务必利用这个功能。
让生成的文档真正有用的关键细节
光有模板不够，内容质量决定文档价值：
立即学习“Java免费学习笔记（深入）”；
- 描述行为，不描述代码：写 “计算订单总金额，含税与运费” 而非 “调用 getSubtotal() + getTax() + getShipping()”。前者说明目的，后者只是复述实现。
-
@param 描述语义，不写类型：IDE 已显示类型，重点写用途。例如：
* @param userId 用户唯一标识，不能为空字符串或 null
* @param timeoutMs 连接超时阈值，建议 1000~30000 -
用 {@link} 关联内部元素：在注释中链接到其他类、方法或字段，提升可读性。例如：
* @see #validateUser(String)
* @see com.example.util.DateUtils#parseISO8601(String) -
包级文档用 package-info.java：在每个包根目录下建
package-info.java文件，用 /** */ 写包作用、模块边界、常见使用模式。这是生成包概览页的基础。
自动化验证与持续维护
高质量文档需要工具兜底：
-
启用编译期检查：在 Maven 的
maven-javadoc-plugin中配置<failonerror>true</failonerror>，强制要求 public 成员必须有 Javadoc，避免遗漏。 - 集成 Checkstyle 或 Google Java Format：配置规则检查 Javadoc 是否缺失、@param 是否完整、空行是否合规，CI 流水线自动拦截不达标提交。
-
定期生成预览：本地运行
mvn javadoc:javadoc查看生成效果，确认链接是否有效、描述是否清晰、排版是否可读——文档是给人看的，不是给机器交差的。
