代码里最难的不是写逻辑，是起名字

上个月 code review 的时候，我看到同事写了一个方法叫 handleData。

点进去一看，一百二十行。先从数据库查三张表，做字段映射，调外部 API 拿汇率，格式化金额，写日志，发 MQ 消息，最后返回一个 DTO。

这个方法做的事情大概是：“计算用户跨境订单的到手价”。

但它叫 handleData。

我没忍住在 review 里写了一句：这名字跟”做一件事”的信息量差不多。

名字是代码的第一道注释

handleData 这种命名有个毛病——它什么也没说。每个方法都在 handle data，就像每个快递员都在”送东西”，但你永远不会把”送东西”写在职场上。

好的命名应该回答一个问题：这段代码在处理什么数据？为什么要处理它？

举个例子。我在一个支付系统里见过这两个写法：

# 写法一
def process(p1, p2, p3):
    ...

# 写法二
def calculate_refund_amount(
    original_order: Order,
    return_reason: ReturnReason,
    customer_tier: str
) -> Decimal:
    ...

第二种写法，你甚至不用看实现，光读函数签名就知道它在干嘛。参数名本身就是文档。

我见过最糟糕的命名

说几个真实的（隐去公司名）。

有个前辈写了一个工具类，里面全是以 _v1、_v2、_v3 结尾的方法。我问他这些版本号什么意思。他说：不知道，可能是第一版、第二版、第三版吧。我翻了 git 历史，发现根本不是按迭代顺序来的，就是他每次懒得想名字就加个数字。

还有一个系统里，核心变量叫 flag。一百多个文件里到处都是 flag = True、if flag:、flag2 = False。后来维护的人辞职了，新来的人花了三天才搞明白 flag 和 flag2 分别代表”是否为VIP用户”和”是否使用新价格策略”。

这些烂名字不是”不优雅”，它们是真的会害人。读代码的人要在脑子里建立一个从烂名字到真实含义的映射，每读一次就要映射一次。 这个认知负担累积起来，就是那句话——“这代码屎山我看不下去了”。

什么时候 AI 能帮你起名字？

去年我开始用 AI 辅助编程之后，发现了一个意外的好处：AI 起名字比我认真。

不是开玩笑。人在快速写代码的时候，脑子里想的是逻辑，手在键盘上飞，变量名随手敲一个 temp、result、data 就过去了。事后也不会回头改，因为”能跑就行”。

但 AI 不会这样。你给它一段逻辑描述，它生成的代码里，变量名通常是完整的、语义明确的。比如我让 Claude 写一个”获取用户最近七天的登录时长”，它给出来的：

recent_login_duration = get_user_login_duration(
    user_id=user.id,
    days=7
)

而不是我在赶时间时会写的：

t = get_login(user.id, 7)

但 AI 也有翻车的时候。

有一次我让它重构一段旧代码，里面有个变量叫 x。AI 尊重了原名，在上下文里一直沿用 x，甚至给它加了一行注释：”x represents the current user’s remaining credit balance”。

我就想问，既然都知道它是什么了，为什么不直接改名叫 remaining_credit 呢？

所以 AI 能帮你起名字，但前提是你得在 prompt 里明确要求，或者至少审查它生成的名字是不是真的有意义。

我现在的命名习惯

踩了足够多的坑之后，我给自己定了几个不成文的规矩。

变量名写完整，不缩写。 除非是全行业通用的缩写（URL、API、DTO），否则 user_name 不要写成 un，payment_status 不要写成 ps。省下的三个字符不值得后面的人猜半天。

布尔值用 is/has/can 开头。 is_vip、has_pending_orders、can_refund。读 if is_vip 比读 if vip 通顺得多，因为前者是一个判断句，后者像个名词。

函数名用动词开头，而且要具体。 handle、process、do 这三个词应该从函数命名里封杀。calculate_refund_amount 比 process_payment 好读十倍。

避免单个字母变量，除非在极短的作用域里。 循环变量 i、j、k 我接受，因为就三行代码的事。但如果一个变量要跨十五行使用，给它一个有意义的名字。msg 总比 m 好。

最关键的：写代码的时候慢下来三秒钟，想一下这个名字一年后自己还看不看得懂。 这三秒钟的投入，回报率比任何技术架构优化都高。

命名和重构

有时候你发现一个名字起得不好，但改起来牵一发动全身。比如一个数据库字段 type，几十个查询、几百行代码都在用，你想改成 payment_type，怕改出 bug。

我以前的做法是”算了下次再说”，然后这个”下次”永远不会来。

后来我想通了：改名是最低成本的重构。IDE 的全局替换功能用好了，一个变量名从 t 改成 login_duration 就是十秒钟的事。如果测试能过，那就改了。如果怕有遗漏，grep 一下旧名字，确认没有遗漏引用。

别等到代码变成屎山才想起来要改。那个时候，你会发现每块砖上面都写着”handleData”，而你已经分不清哪块砖该放在哪里了。

代码是写给人看的，顺便让机器执行。而名字，是人读代码时看到的第一样东西。花点心思在这上面，不为别的，就为了三个月后自己回头看不骂自己。