“I just chose words carefully”
来源：HackerNews
# "I just chose words carefully"：代码命名背后的技术哲学
在软件开发领域，有一句广为流传的谚语："计算机科学中只有两件难事：缓存失效和命名。"（There are only two hard things in Computer Science: cache invalidation and naming things.）当我们谈论代码质量时，往往首先想到算法复杂度、架构设计或性能优化，却常常忽略了最基础也最关键的环节——**词汇选择**。
最近在 HackerNews 上引发热议的一篇文章 *"I just chose words carefully"*（我只是仔细选择了措辞），恰好切中了这一被忽视的技术实践。作者通过多个实际案例展示了：优秀的软件设计并非来自高深的技巧，而是源于对每一个变量名、函数签名和错误提示的精心打磨。这种"措辞优先"的编程哲学，正在重新定义我们对代码优雅性的理解。
## 核心内容
### 1. 语义精确性优于注释
传统的编程教学鼓励我们"写清晰的注释"，但更好的做法是**让代码自我解释**。作者举了一个典型例子：与其写 `// calculate total price with tax`，不如直接将函数命名为 `calculateTotalPriceIncludingTax()`。精确的长名称胜过模糊的短名称加注释，因为注释会过时，而名称是代码的契约。
### 2. 消除语境依赖的歧义
在复杂的业务系统中，同一个词汇往往有多个含义。比如 `user` 可能指系统用户、当前登录者或数据库记录。作者建议采用**语境前缀模式**：
- `authenticatedUser` 而非 `user`
- `rawUserData` 而非 `data`
- `userRepository.findById()` 而非 `user.get()`
这种"防御性命名"策略能显著降低代码审查时的认知负荷。
### 3. 错误信息的用户视角
技术团队常犯的一个错误是用实现细节描述异常。对比以下两种错误提示：
- 技术视角：`"JSON parsing failed at line 42"`
- 用户视角：`"We couldn't read your configuration file 'settings.json' because it contains invalid formatting on line 3"`
后者虽然长了几个单词，但直接指向解决方案。措辞的选择决定了调试效率。
### 4. 布尔值的肯定性命名
对于布尔变量，作者强调应避免否定式命名（如 `isNotValid`），而选择肯定式（`isValid`）。这不仅是语法习惯，更关乎逻辑可读性。`if (!isNotValid)` 的双重否定比 `if (isValid)` 多消耗 50% 的认知资源。
## 技术分析
从认知心理学角度看，这种"措辞优先"的方法符合**认知负荷理论**（Cognitive Load Theory）。人类工作记忆一次只能处理 4±1 个信息组块。当代码命名含糊时，大脑需要额外的"解码"过程，占用本应用于理解业务逻辑的心智资源。
在架构层面，精确的词汇选择实际上是**领域驱动设计**（DDD）中"通用语言"（Ubiquitous Language）的微观实践。当开发者在代码中使用与业务专家完全一致的术语时，技术实现与业务模型之间的不匹配（Impedance Mismatch）自然消解。例如，在电商系统中，使用 `fulfillOrder()` 而非 `processOrder()`，因为它准确对应了业务流程中的"履约"概念。
此外，现代 IDE 的自动补全和类型推断技术，已经消除了"长变量名影响编码速度"的顾虑。研究表明，开发者阅读代码的时间远多于编写时间（比例约为 10:1），因此投资在命名上的时间具有极高的 ROI。
## 实践建议
对于希望在团队中推广这一理念的开发者，建议采用以下实践框架：
**命名前的"三问法"**：
1. 这个名字在六个月后的代码审查中是否依然清晰？
2. 如果删除所有注释，新同事能否通过名称理解意图？
3. 这个词汇是否与产品经理使用的业务术语一致？
**建立团队词汇表**：
创建一个 `GLOSSARY.md` 文件，统一关键概念的英文表达。例如明确规定：
- `fetch` 用于远程数据获取，`get` 用于内存访问
- `validate` 返回布尔值，`assert` 抛出异常
- `temp` 禁止作为变量名（临时变量也需要描述其临时保存的内容）
**代码审查中的"命名检查单"**：
- 检查缩写是否必要（`auth` vs `authentication`）
- 检查单位是否明确（`timeout` vs `timeoutInMilliseconds`）
- 检查动作是否完整（`handle` 是模糊词，应具体为 `parse`、`validate` 或 `transform`）
## 总结
在 AI 辅助编程日益普及的今天，"I just chose words carefully" 这一理念显得尤为重要。当机器可以生成代码骨架时，人类开发者的价值正转向更高层次的抽象与精确表达。好的命名不仅是代码风格问题，更是技术同理心的体现——它考虑的是下一个阅读这段代码的人，是在凌晨三点调试系统的工程师，是六个月后的自己。在这个意义上，仔细选择措辞不仅是一种技术实践，更是一种专业素养的彰显。