java变量声明与代码文档化是协同构建可读、可维护、易协作代码的双支柱；变量需类型明确、位置精准、命名达意，局部变量应显式初始化并靠近首次使用处。
Java变量声明和代码文档化不是两个孤立环节，而是协同构建可读、可维护、易协作代码的双支柱。变量命名不清，Javadoc再全也难懂逻辑；文档缺失，再规范的变量名也难说清用途边界。
变量声明：类型明确、位置精准、命名达意
声明变量时，核心是让每个变量“自我说明”——谁用、在哪用、怎么用、值从哪来。
-
局部变量必须显式初始化，且尽量靠近首次使用处：比如循环计数器写成
for (int i = 0; i ，而不是先 <code>int i;再赋值。未初始化就访问会直接编译失败，这是Java强制的安全兜底。 -
成员变量不依赖默认值：声明
private List<string> tags;</string>后直接调用tags.add(...)会空指针；应写成private List<string> tags = new ArrayList();</string>或在构造器中完成初始化。 -
命名严格遵循语义优先原则：用
isEmailVerified而非flag1，用MAX_RETRY_ATTEMPTS而非maxRetry（后者缺少常量标识）；数组统一用String[] userNames形式，强调类型完整性。 -
禁止作用域遮蔽：方法内已声明
String name，就不能在 if 块里再写String name = "guest";—— 编译器会拒绝，倒逼你换名如fallbackName或重构逻辑。
Javadoc：描述意图，而非复述代码
好的文档注释让人一眼明白“为什么这么设计”，而不是“这行写了什么”。它面向的是调用者，不是写作者自己。
-
每个 public 类、方法、字段都应有 Javadoc：哪怕只有一行，也要说明用途。例如：
/** 用户登录失败后允许的最大重试次数，默认为3 */比// max retry count信息量大得多。 -
@param、@return、@throws 必须准确对应签名：方法参数名拼错、返回值类型写成
void却实际返回boolean，会导致生成的 HTML 文档失真，误导下游使用者。 -
避免“同义重复”注释：不要写
// 计算总和紧跟int sum = a + b;；而应说明业务含义，比如/** 返回订单含税总金额，已包含运费与平台服务费 */。 - 复杂逻辑或非常规行为必须标注：如方法内部会修改传入集合、可能静默吞掉异常、或对 null 输入有特殊处理，都要在文档中明确，不能靠“看代码才知道”。
声明与文档的协同检查点
变量和文档不是写完就完的事，它们之间存在天然校验关系。几个关键交叉点值得日常留意：
-
变量名与 Javadoc 中的术语保持一致：如果字段叫
userProfileCache，文档里就别写成 “stores user config data” —— cache 和 config 是不同概念，容易引发误解。 -
final 变量必须在文档中体现不可变性：
/** 服务超时阈值（毫秒），初始化后不可更改 */配合private final int timeoutMs;，比单纯写timeoutMs更具契约感。 -
静态常量的文档要说明全局影响：比如
public static final int DEFAULT_PAGE_SIZE = 20;的文档应注明“影响所有分页接口的默认行为，修改需同步评估上下游”。 - IDE 能帮但不能代劳：IntelliJ 可自动生成 Javadoc 框架，也能高亮未初始化变量，但是否选对类型、是否写清边界条件、是否覆盖异常路径——这些仍取决于开发者对业务的理解深度。
变量声明和文档化，本质上都是在为他人（包括未来的自己）降低认知成本。写清楚一个变量，比写十行注释更有力；写准一行 Javadoc，有时胜过翻半天源码。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
