变量命名必须准确表达类型、作用域和语义边界，如usercount、activeusercount、maxretryattempts；布尔变量须用is/has/can前缀且遵循javabeans规范；集合名应体现业务域、特征与元素类型；好命名可消除注释需求并提升工具分析准确性。
变量名本身就要能说明“它是什么”
很多人写 int a = getUserCount();，然后靠 Javadoc 解释 a 是用户总数。这等于把本该由名字承担的责任推给注释。变量名不是占位符，是契约——它得让读代码的人一眼知道类型、作用域和语义边界。
比如：userCount 比 a 明确；activeUserCount 比 userCount 更精确；maxRetryAttempts 直接表达了约束意图，不需要额外写 @param maxRetryAttempts maximum number of retries。
常见错误现象：
- 用单字母或缩写（
tmp,lst,req）代替完整语义 - 命名和实际用途脱节（
response实际存的是解析后的 DTO，不是原始 HTTP 响应） - 在 if/for 内部用
i,j循环，但嵌套三层后没人记得j对应哪层数据
布尔变量命名必须带 is/has/can 等语义前缀
这是最容易踩坑的点。Boolean deleted 和 Boolean isDeleted 看似只是风格差异，但框架（如 FastJSON、MyBatis、Spring Data）会按 JavaBeans 规范反射 getter 方法。如果字段叫 isDeleted，框架默认找 getIsDeleted() 或 isIsDeleted()，而不是 isDeleted() —— 导致序列化失败或字段为空。
正确做法是：布尔字段名直接用 isXxx 形式，且不加额外前缀；getter 方法由 IDE 自动生成（如 isExpired()），字段就叫 expired。
所以：private boolean expired; → isExpired()，不是 private boolean isExpired; → isIsExpired()。
关键参数差异：
-
expired：符合 JavaBeans，框架能正确映射 -
isExpired：触发框架误判属性名为expired，但字段名却是isExpired，造成空值或 NoSuchFieldException -
canRetry,hasPermission,shouldLog：这类命名自带动词+宾语结构，无需注释解释返回逻辑
集合和容器类变量名要体现元素类型和业务含义
写 List users = getUsers(); 是危险的。它没说清楚是全部用户、当前租户用户、还是缓存中的用户快照。更糟的是，IDE 自动补全或重构时，users 这种泛化名会让类型信息彻底丢失。
推荐组合方式：[业务域] + [集合特征] + [元素类型]，例如：
-
activeUserList（非 null 的 ArrayList，含活跃用户） -
userRoleMap（Map，key 是 user ID） -
pendingOrderIds（Set，待处理订单 ID 集合）
这样连 @return List<user></user> 都可以省略——名字已说明类型和状态。而如果真要写 Javadoc，重点就该放在“为什么是 active”“pending 的判定条件是什么”，而不是“这个 List 存什么”。
避免用注释解释命名，而是用命名消除注释需求
当你发现自己在写类似这样的 Javadoc 时，就是命名失败的信号：
/** * 用户登录态标识（true 表示已登录） */ private boolean loginStatus;
这段注释其实在纠正名字的歧义：loginStatus 可能被理解为枚举、字符串或时间戳。真正清晰的命名是 isLoggedIn —— 它天然绑定布尔语义，且与 getter isLoggedIn() 一致，框架兼容，人眼可读，Javadoc 可删。
容易被忽略的地方是：命名质量直接影响静态分析工具的效果。比如 SonarQube 对 userList 和 currentUserList 的空值风险评估完全不同；IDE 的重命名重构在语义明确的变量上才敢跨文件安全执行。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
