“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" 这一理念显得尤为重要。当机器可以生成代码骨架时，人类开发者的价值正转向更高层次的抽象与精确表达。好的命名不仅是代码风格问题，更是技术同理心的体现——它考虑的是下一个阅读这段代码的人，是在凌晨三点调试系统的工程师，是六个月后的自己。在这个意义上，仔细选择措辞不仅是一种技术实践，更是一种专业素养的彰显。