合理使用注释应解释“为什么”而非“做什么”。通过说明意图、划分逻辑块、标记待优化点及完善API文档，提升代码可读性与维护性，实现有效沟通。
在Java中，当代码涉及复杂逻辑时，合理使用注释能显著提升代码的可读性和可维护性。关键不在于注释多少，而在于是否清晰传达了“为什么”这么做，而不是重复“做了什么”。下面是一些实用的方法和示例。
说明意图而非行为
复杂逻辑往往源于业务规则或算法设计。此时应解释为什么要这样实现，而不是描述代码本身。
例如：// 根据用户等级计算折扣，高级会员在促销期间额外增加5%
// 避免与基础折扣叠加溢出，因此限制总折扣不超过70%
double totalDiscount = baseDiscount + (isPremium ? 0.05 : 0);
if (totalDiscount > 0.7) {
totalDiscount = 0.7;
}
这里的注释解释了业务背景和限制原因，帮助后续开发者理解边界条件的来源。
拆分逻辑块并添加段落注释
对于长方法中的多个处理阶段，用注释划分逻辑段落，使结构更清晰。
立即学习“Java免费学习笔记（深入）”；
例如：// 1. 验证输入参数合法性
if (input == null || input.isEmpty()) {
throw new IllegalArgumentException("输入不能为空");
}
// 2. 预处理：清洗数据并标准化格式
input = input.trim().toLowerCase();
// 3. 执行核心匹配算法（基于编辑距离）
int distance = calculateEditDistance(input, target);
// 4. 判断是否符合匹配阈值
return distance <= MAX_THRESHOLD;
每个阶段前的注释让读者快速定位功能模块，无需逐行推断。
使用TODO和FIXME标记待优化点
如果某段复杂逻辑是临时方案或存在性能隐患，可用特殊注释提醒后续处理。
// TODO: 当前正则表达式性能较差，大数据量下需替换为状态机实现
Pattern pattern = Pattern.compile("(a+)+b"); // 易引发回溯灾难
这类注释能有效传递技术债务信息，便于团队协作追踪。
配合Javadoc说明公共API的复杂行为
对于公开方法，尤其是返回值或异常有特殊规则时，用Javadoc详细说明。
例如：/** * 计算任务执行优先级 * * 算法综合考虑等待时间、资源占用和用户等级。 * 优先级 = (等待时间 / 60) * 0.3 + 资源权重 * 0.4 + 用户等级 * 0.3 * 注意：结果会做归一化处理到[0, 1]区间 * * @param task 当前任务，不能为空 * @return 优先级值，范围[0.0, 1.0] * @throws IllegalStateException 若任务状态不为PENDING */
这能让调用者准确理解方法行为，减少误用。
基本上就这些。关键是把注释当作沟通工具——写给未来的自己或同事看的解释，而不是代码的复读机。
