命名和注释是提升代码可理解性、可交接性与可维护性的关键起点；好命名明确主体与行为（如currentuserprofile、fetchlatestorderstatusfromapi），类名体现职责（如paymentvalidator），常量名暴露约束（如max_retry_attempts），javadoc聚焦“为什么”和“怎么用”，行内注释仅解释反直觉逻辑。
命名和注释不是“锦上添花”，而是让代码从“能运行”变成“可理解、可交接、可维护”的关键起点。好命名减少注释需求，好注释补足命名无法表达的意图——二者协同，直接降低阅读成本与出错概率。
变量和方法名要像句子一样说清“谁在做什么”
命名不是起代号，是传递语义。避免userInf、getData这类模糊写法：
- 用currentUserProfile代替userInf——明确主体（当前用户）、对象（档案）和粒度（profile而非inf）
- 用fetchLatestOrderStatusFromApi代替getData——说明动作（fetch）、目标（latest order status）、来源（API）
- 循环计数器可用i、j，但业务逻辑中别用tmp、val；retryCount比cnt更安全
类名体现职责，常量名暴露约束
类是系统中的“角色”，名字必须回答“它代表什么、负责什么”：
- PaymentValidator 比 Check 更准确——它验证支付，不是泛泛地“检查”
- CsvOrderImporter 比 ImportUtil 更具体——格式（CSV）、领域（订单）、行为（导入）全涵盖
- 常量如MAX_RETRY_ATTEMPTS、DEFAULT_TIMEOUT_MS，既表明上限/默认值，也带单位或上下文，避免魔数散落
Javadoc 注释聚焦“为什么”和“怎么用”，不是复述代码
方法上方的/** */不是装饰，是接口说明书：
- 写清楚参数含义：@param userId 用户唯一标识，不能为空，格式为8位数字字符串
- 说明返回值边界：@return 成功时返回非空Order对象；若订单不存在则返回null
- 标出异常场景：@throws IllegalArgumentException 当userId格式非法时抛出
- 不写“设置用户名”这种废话，改写“将用户昵称同步至消息推送服务，需保证线程安全”
行内注释只解释“反直觉”逻辑，不解释语法
注释是用来对抗认知偏差的，不是翻译Java语法：
- ✅ 好注释：// 使用Math.floorDiv避免负数除法向零截断（-5/2= -2，但floorDiv=-3）
- ❌ 坏注释：// i++ 自增、// if判断是否为空
- 复杂算法段落前加简短说明，比如// 使用双指针跳过连续重复字符，时间复杂度O(n)
- 临时绕过问题的代码旁标注 TODO + 原因：// TODO: 替换为Redis分布式锁（当前单机锁在集群下失效）
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
