在Java中注释如何书写_Java单行与多行注释说明

Java注释分//、/.../和/.../三类：//用于单行，不跨行且不可在字符串内；/.../支持多行但禁止嵌套；/.../为Javadoc注释，需紧邻声明且含标准标签。

Java 中注释不是可有可无

的装饰，而是影响代码可维护性、IDE 行为甚至编译结果的关键部分——比如 @Deprecated 的生效依赖 Javadoc 注释结构，而误用多行注释嵌套会导致编译失败。

单行注释用 //，但别在字符串或字符字面量里乱加

// 从出现位置开始到行尾全部忽略，不跨行。它安全、轻量，适合临时禁用代码或写简短说明。

• ✅ 正确：在逻辑行首或语句后添加，如 int x = 1; // 初始化计数器
• ❌ 错误：写在字符串内部，如 String s = "hello // world"; —— 这里的 // 是字符串内容，不会被当注释，也不会截断字符串
• ⚠️ 注意：// 不会跳过换行符，所以不能用来“注释掉”含换行的多行表达式（比如拆成多行的 long 方法调用），必须每行都加

多行注释用 /* ... */，但严禁嵌套

/* 到下一个 */ 之间的所有内容（含换行）都被忽略。它适合临时屏蔽大段代码，也用于写较详细的说明。

• ✅ 正确：/* 这是合法的多行注释，可以跨行 */
• ❌ 致命错误：/* 外层注释 /* 内层注释 */ 继续外层 */ —— Java 不支持嵌套，第一个 */ 就结束整个注释，后续文本可能引发编译错误
• ⚠️ 注意：如果用它注释掉一段含 /* 或 */ 的代码（比如正则表达式或 SQL 字符串），容易意外提前终止注释，建议改用连续 //

Javadoc 注释是 /** ... */，不是普通多行注释

只有以 /** 开头、*/ 结尾的块，且紧邻类/方法/字段声明上方，才会被 javadoc 工具识别为文档注释。它有固定标签语法，比如 @param、@return。

• ✅ 正确：

  /**
   * 计算两个整数之和
   * @param a 加数
   * @param b 被加数
   * @return 和
   */
  public int add(int a, int b) { return a + b; }

• ❌ 无效：/* 这只是普通多行注释，javadoc 工具完全忽略 */
• ⚠️ 注意：Javadoc 注释中若漏写 @param 标签，某些 IDE 会警告；但更隐蔽的问题是，如果在方法体内部写了 /** ... */，它虽不报错，却不会生成文档，还可能误导他人

真正容易被忽略的是注释与代码边界的模糊性——比如在 if 条件后直接跟 //，看似注释，实则可能掩盖逻辑歧义；又比如用 /* 注释掉半行语句，导致语法残缺。注释不是“写给人看的”，而是“写给此刻和三个月后的自己看的”，它的存在本身就应该经得起重读和重构。