17370845950

Java注释是提升可读性、协作与维护的关键，含//、/.../、/*.../三种形式，分别用于单行说明、临时禁用代码和生成API文档；好注释应解释“为什么”，而非重复“做什么”，Javadoc需规范使用@param、@return等标签，团队须遵守注释纪律。

Java中的注释不是可有可无的装饰，而是代码可读性、协作效率和长期维护的关键支撑。写得对，能帮别人（包括未来的你）秒懂逻辑；写得乱，反而制造噪音，甚至误导。

三种标准注释形式与适用场景

Java只支持三种官方注释语法，每种定位明确，混用或误用会削弱表达力：

• 单行注释（//）：用于简短说明，比如解释某一行的特殊处理、临时跳过逻辑、标注待办事项。不要用它写大段描述，也不该跨多行堆砌。
• 多行注释（/* ... */）：适合临时注释掉一段代码，或在极少数需要跨行说明但不参与文档生成的场合。注意它不能嵌套，且不被Javadoc工具识别。
• 文档注释（/** ... */）：唯一能被Javadoc提取生成API文档的注释。必须放在类、接口、方法、字段等成员声明之前，配合标准标签如 @param、@return、@throws 使用，才算真正“生效”。

什么该写，什么不该写——注释的内容守则

好注释回答“为什么”，而不是重复“做什么”。代码本身已说明行为时，再写就是冗余：

• ✓ 写清楚设计意图：比如 “此处使用双重检查锁而非synchronized，是为了避免每次调用都加锁开销”
• ✓ 标注边界条件或隐含约束：“输入字符串长度不得超过256字节，否则触发底层协议截断”
• ✗ 别翻译代码：“i++ // 将i加1” —— 这等于没说
• ✗ 别写过期信息：修改逻辑后忘记更新注释，比不写更危险。发现注释和代码不符，优先信代码，再同步修正注释。

Javadoc不是摆设——写出真正可用的API注释

一个合格的public方法文档注释，至少包含三要素：

• 简洁的功能概述：首句用动词开头，说明方法作用，例如 “计算用户账户当前可用积分”
• @param 参数说明：每个参数一行，讲清取值范围、是否允许null、特殊含义
• @return 或 @throws：返回值非空/可能为null需注明；受检异常必须列出，运行时异常酌情说明触发条件

示例：
/**
* 根据订单ID查询订单详情，若订单不存在则返回null。
* 注意：仅支持状态为'PAID'或'PROCESSING'的订单。
* @param orderId 订单唯一标识，不能为空且必须为正整数
* @return 订单对象；若未找到或状态非法，返回null
* @throws IllegalArgumentException 当orderId ≤ 0时抛出
*/

团队协作中的注释纪律

注释是团队契约的一部分，不是个人笔记：

• 公共模块的接口、核心算法、配置项含义，必须配Javadoc，CI流程可接入javadoc:jar校验缺失率
• 禁止在代码中留“TODO: 后续优化”却不带责任人和时限；建议写成 “TODO(张三, 2025-Q3): 替换为Redis缓存，当前DB查询已成瓶颈”
• 删除废弃代码时，连带清理相关注释；保留的注释必须与现存逻辑一致

基本上就这些。注释不是越多越好，而是越准越好——准确传达意图，诚实反映现状，尊重阅读者的时间。