好名字胜过注释：代码命名的四个原则
一段代码会被写一次，却会被读很多次——被同事读、被评审读、被六个月后忘记一切的你自己读。所以代码里出现频率最高、影响最大的“注释”，其实是命名。一个叫 data1、temp、list 的变量，每次出现都在强迫读者停下来猜测：这到底是什么？而一段命名清晰的代码，几乎不需要额外解释。命名不是小事，它是代码质量的晴雨表。
为什么命名本质上是设计问题
给一个变量、函数或类起名困难，往往不是词汇量问题，而是概念本身没想清楚：如果你说不清这个变量“是什么”，它很可能就不该存在，或者应该被拆成几个概念。反过来，命名清晰的过程会倒逼设计清晰——名字是概念的载体，概念模糊时名字必然含糊。从认知角度看，含糊的名字给读者制造的是持续的小型打断：每遇到一个“猜不透的名字”，大脑就要暂停阅读去推断语义，心流被反复切断，理解成本成倍上升。Google 的代码风格指南把命名放在重要位置，核心原则就一句话：让代码易于新读者理解，比节省几个字符重要得多。
四个命名原则：从“能跑”到“能读”
原则一：描述性优先于简短。用 maxRetryCount，不用 mrc；用 userProfile，不用 up。缩写省下的三个字符，代价是读者每次都要解码。少用缩写、多用完整单词，是风格指南的共识。例外是局部公认的短名：循环里的 i、j，数学公式里的 x、y，作用域极小且约定俗成，可以保留。
原则二：命名说“是什么”，不说“怎么来的”。变量名应该反映语义而不是实现细节：一个存用户列表的变量叫 users 就好，不必叫 usersFromDatabase；函数叫 getUserProfile，而不是 doQuery。最该警惕的是 data、tmp、result 这类“无信息名”——它们等于没命名。布尔变量习惯用 is、has、can 开头（isReady、hasPermission），读起来像一句自然语言。
原则三：同一概念同一词，不同概念不同词。如果 fetch、get、load、query 在你的代码里表示同一种操作，读者会以为它们是四种操作；如果 customer 和 client 混用指同一个角色，搜索时就会漏掉一半。团队应该有一份简单的术语共识，让整个代码库看起来像一个人写的——命名一致性本身就是可读性。
原则四：名字里带上单位、边界与语境。涉及数值时把单位写进名字：timeoutMs、maxSizeBytes、priceInCents，一个后缀能消灭一整类单位换算 bug。避免歧义和双重否定：能用 isActive 就不用 isNotDisabled。另外，名字长度要匹配作用域：局部变量可以短，跨模块、对外暴露的函数和类，名字要完整到能独立表达意图。
一个真实案例：一个叫 list 的变量引发的线上事故
一支电商团队维护着一个老支付模块，里面有个变量叫 list——有时是订单金额数组，有时是手续费率，全看它在哪个函数里出现。一次促销活动上线，新来的工程师在计算折扣时把手续费率数组当成了金额数组使用，三百多笔订单被多扣了款，客服电话被打爆，团队排查到凌晨两点才定位到问题。复盘时老员工苦笑：这个变量刚写出来时叫 list，后来功能迭代了好几次，名字从来没跟着改。事后团队做了两件事：把相关变量全部改名为带单位的自解释名字，比如 chargeRatesInPercent、orderAmounts；立了一条评审规矩——review 时任何人说“这个名字我看不懂”，代码就要打回重命名。此后半年，同类问题再没出现过。差命名省下的几分钟，最终以几万块的退款和一夜的加班还了回去。
常见误区与避坑
- 追求极简短名。单字母变量成片出现，代码成了密码本。省字符的快感，远小于读者解码的痛苦。
- 用 data、tmp、thing 充数。名字说不清用途，等于这个变量在代码里“匿名生存”，迟早出事。
- 逻辑改了名字不改。函数名叫 getUser 却偷偷写了库，是最危险的命名——读者基于名字建立的心智模型会彻底误导。
- 中英混杂与拼音命名。代码语言要团队统一，混用会割裂搜索和阅读。宁可全英文，不要“get用户列表”。
- 忽略可搜索性。好名字能被 grep：想找“处理退款”的逻辑，搜 refundProcess 一次命中；搜 temp 会命中五百处。命名时要想着未来的搜索者。
- review 时对差命名沉默。“名字看不懂”是最正当的打回理由。评审时不提，坏名字就会代代相传。
行动建议
今天就打开最近的代码，用 IDE 的重命名功能重构三个让你皱眉的名字——重点处理 data、temp、result 这类无信息名和名不副实的函数。给自己定一份命名检查清单：这个名字能读出意图吗？带单位或边界了吗？和团队术语一致吗？从下一个 PR 开始，把“名字是否自解释”写进你的评审标准。代码是写给机器执行的，更是写给人类读的——而名字，就是代码与人之间的界面。