java代码注释

Java代码注释规范

 

一、注释类型与用途

 

1. 文档注释（Javadoc）

- 格式： /** ... */ ，用于类、方法、字段的说明，可生成API文档。

- 类注释：说明功能、职责、作者、版本等。

- 方法注释：说明功能、参数、返回值、异常（用 @param   @return   @throws ）。

- 字段注释：说明静态常量或关键字段的含义。

2. 行注释（单行注释）

- 格式： // 注释内容 ，用于解释代码块或关键行，侧重说明“为什么”而非“是什么”。

3. 块注释（多行注释）

- 格式： /* ... */ ，用于临时注释代码块，不推荐频繁使用（避免注释与代码逻辑脱节）。

 

二、注释规范原则

 

1. 文档注释规范

- 类注释需体现业务含义和职责，方法注释需明确参数作用及返回值逻辑。

- 静态常量必须添加文档注释，说明其代表的业务含义（如 MAX_TIMEOUT 表示最大超时时间）。

2. 行注释原则

- 注释应简洁，聚焦代码逻辑的背景或特殊处理（如兼容旧版本、性能优化点）。

- 注释与代码逻辑保持同步，代码修改时需更新对应注释。

3. 注释维护

- 废弃代码建议通过版本控制工具（如Git）管理，而非直接注释保留。

- 避免过度注释（如每一行代码都添加注释），保持代码可读性优先。

 

三、注释工具与约定

 

- Javadoc注释遵循标准语法，可通过IDE（如IDEA）自动生成模板，参数名需与方法定义一致。

- 行注释建议与代码保持合理缩进，同一代码块内的注释风格需统一（如注释位于代码上方或右侧）。