变量声明的语义化：怎样让代码更易读

语义化命名要求变量名直说用途、见名知意，避免缩写与谜语，遵循语言惯例（如Python用snake_case、Java用camelCase），配合类型与结构封装业务概念，使名字在上下文中自然生效。

变量声明的语义化，本质是用名字讲清楚“它是什么、用来干什么”，而不是让别人去猜。名字不是标签，是契约——看到名字，就该知道它的角色、范围和意图。

命名要直说用途，不玩缩写和谜语

一个变量名如果需要注释才能看懂，那它已经失败了。语义化命名的核心是“见名知意”。

• 用 employeeCount，不用 empCnt 或 eC；后者省了几个字符，却多花了三秒理解时间
• 用 isOrderConfirmed，不用 flag1 或 status；布尔变量前加 is/has/can 是通用信号
• 避免拼音（如 yonghu）或中英混杂（如 用户列表userList），统一用英文短语表达业务概念

匹配语言习惯，别跨风格乱套

不同语言有默认共识，强行统一反而降低可读性。

• Python 推荐 snake_case： max_retry_times、user_profile_data
• Java/TypeScript 用 camelCase： maxRetryTimes、userProfileData
• 常量统一大写加下划线：API_TIMEOUT_MS、DEFAULT_PAGE_SIZE
• R 里允许点号，但优先选 snake_case 或 camelCase，避开 .data 这类易混淆开头

结构复杂时，别硬塞在变量名里

当数据本身有明确含义，就该封装，而不是靠名字“描述结构”。

• ❌ order_items_list_with_ids —— 名字太长，还暴露了实现细节
• ✅ pendingOrders —— 配合类型定义或类封装，直接体现业务状态
• 更进一步：用 class Order 封装 id、items、status 等字段，变量名回归业务角色，如 currentOrder、archivedOrders

配合代码结构，让名字真正起作用

好名字不是孤立存在的，它得在上下文中自然生效。

• 链式操作中提取中间结果： const activeUsers = users.filter(isActive)，比直接 users.filter(u => u.active) 更易定位逻辑断点
• 函数参数命名体现职责：formatReport(reportData, dateFormat) 比 formatReport(data, fmt) 更容易排查调用错误
• 局部变量不必过度修饰，但作用域稍大时需明确边界：在函数顶部声明 finalTaxAmount，比循环里反复算 total 更安全、更可读