Java注释写法：单行多行规范详解

Java注释看似简单，实则是提升代码可读性、协作效率与长期可维护性的关键实践——本文系统详解三种注释（单行//、多行/*...*/、文档/**...*/）的正确用法、典型场景与常见陷阱：从如何简洁标注逻辑、安全屏蔽代码，到规范编写可生成Javadoc的API文档；更强调注释不是装饰，而是责任——需同步更新、拒绝冗余、不掩盖问题，并倡导团队统一风格。掌握这些细节，让你的代码不仅机器能懂，更让同事一眼心领神会。

Java注释用 // 写单行，用 /* ... */ 写多行，文档注释用 /** ... */ 生成API说明。

单行注释：用两个斜杠（//）

从 // 开始到行末的所有内容都会被编译器忽略。适合简短说明、临时禁用某行代码或标注小逻辑。

• 写在代码上方或同行末尾均可，但建议保持对齐、不挤占可读性
• 避免过度使用，比如每行都加无意义的注释（如 // i++）
• 示例：
  // 计算用户积分，按登录天数累加
  int score = days * 10;
  int bonus = (isVip ? 50 : 0); // VIP用户额外奖励

多行注释：用 /* ... */ 包裹

适用于跨多行的说明、暂时屏蔽一段代码，或写较详细的内部说明。

• 不能嵌套，即 /* ... /* ... */ ... */ 是非法的
• 注意缩进和换行，避免把关键代码意外包进注释里
• 示例：
  /*
    初始化配置参数：
    - timeout：连接超时毫秒数
    - retries：失败重试次数
  */
  config.setTimeout(5000);

文档注释：用 /** ... */ 生成Javadoc

这是专为生成API文档设计的注释，必须放在类、方法、字段等声明之前，支持特定标签（如 @param、@return、@throws）。

• 每个 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)）
• 禁止用注释“掩盖”坏代码（如大段被注释掉的旧逻辑），该重构就重构
• 团队中可约定注释风格（如是否在 // 后加空格、多行注释是否用星号对齐），提升一致性

以上就是《Java注释写法：单行多行规范详解》的详细内容，更多关于的资料请关注golang学习网公众号！