Java注释类型与使用规范详解

一分耕耘，一分收获！既然打开了这篇文章《Java注释类型及规范详解》，就坚持看下去吧！文中内容包含等等知识点...希望你能在阅读本文后，能真真实实学到知识或者帮你解决心中的疑惑，也欢迎大佬或者新人朋友们多留言评论，多给建议！谢谢！

Java注释分三种：单行（//）、多行（/.../）、文档（/*.../）；分别用于行级说明、块级禁用、API文档生成，核心是提升可读性与协作性，且需随代码同步更新。

Java 中的注释共三种：单行注释、多行注释、文档注释。它们用途不同，语法不同，编译器处理方式也不同——但核心目标一致：让代码更易读、可维护、可协作。

单行注释（//）适合快速说明和临时禁用

以 // 开头，作用范围仅限当前行末尾。常用于：

• 解释某一行变量或逻辑的意图，比如 int timeout = 3000; // 单位毫秒，超时阈值
• 临时屏蔽一行代码调试，如 // System.out.println("debug: " + value);
• 标记待办事项，配合 TODO、FIXME 等关键词，例如 // TODO: 后续支持异步回调

注意：不要堆叠多行 // 来模拟多行注释；也不要用它重复代码已明确表达的动作（如 i++; // i加1）。

多行注释（/* ... */）用于块级说明或临时停用代码段

以 /* 开始、*/ 结束，中间内容完全被忽略。适用于：

• 对几行相关代码做整体说明，比如算法步骤、业务规则限制
• 临时注释掉一段暂时不用但可能恢复的代码（比删掉更安全）
• 在调试中批量禁用逻辑分支，例如整个 if 块

关键限制：不能嵌套使用，即 /* 外层 /* 内层 */ 外层 */ 是非法的；但内部可以包含 //，不影响语法解析。

文档注释（/** ... */）是生成 API 文档的唯一标准形式

以 /** 开始、*/ 结束，必须紧贴在类、接口、方法、字段等成员声明之前。它的价值在于可被 javadoc 工具提取并生成 HTML 文档。

合格的文档注释应包含：

• 首句用动词开头，概括功能（如 “验证用户邮箱格式是否合法”）
• 使用标准标签说明关键信息：@param 描述参数含义与约束，@return 说明返回值语义，@throws 列出可能异常及触发条件
• 避免空泛描述，聚焦“为什么这么设计”或“调用者需注意什么”

示例：

// 正确写法
/**
  * 根据手机号查询用户基本信息，不包含敏感字段。
  * @param phone 手机号，11位数字字符串，不能为空
  * @return 用户对象；若未找到或格式非法，返回 null
  * @throws IllegalArgumentException 当 phone 含非数字字符时抛出
  */
public User findUserByPhone(String phone) { ... }

注释不是装饰，而是沟通契约

真正有用的注释回答的是“为什么”，而不是“做什么”。代码本身应尽量自解释（靠命名、结构、拆分），注释则补足那些无法从语法直接看出的信息：

• 隐藏的约束（如“此方法线程不安全，调用方需自行同步”）
• 权衡取舍（如“此处用 HashMap 而非 TreeMap，因无需排序且读多写少”）
• 外部依赖（如“该时间戳来自 NTP 服务器，误差控制在 ±50ms 内”）

一旦代码修改，对应注释必须同步更新；过期注释比没有更危险。

本篇关于《Java注释类型与使用规范详解》的介绍就到此结束啦，但是学无止境，想要了解学习更多关于文章的相关知识，请关注golang学习网公众号！