在Java里如何写注释_Java单行多行注释规范说明

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）。

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