棱镜BLOG

读《代码整洁之道》有感

VitaminE · · #Java

《代码整洁之道》

读《代码整洁之道》有感

代码是写给人看的,只是顺便能被机器执行。 —— 《计算机程序的构造和解释》(SICP)

工作后重读 Robert C. Martin(Bob 大叔)的《代码整洁之道》(*Clean Code*),感受和第一次读时完全不同。刚入行时觉得书里讲的都是"常识";等自己维护过几个"祖传项目",在一个上千行的方法里一行行打断点之后,才明白这些"常识"有多难做到,又有多重要。

这篇不复述全书,只记下几个对我触动最大的点,配上一些 Java 里的例子。


一、关于命名:名字就是最好的文档

书里花了整整一章讲命名,这是我最认同的一部分。好的命名应该让读者不需要注释就能理解意图;变量名应该说明"它是什么、为什么存在",而不是"它是什么类型"。

先看一段很常见的代码:

// 获取列表
List<Order> list1 = orderService.query(uid, 1);
for (Order o : list1) {
    if (o.getFlag() == 2) {
        // ...
    }
}

list1 是什么?1 和 2 又代表什么?读的人只能去翻 query 的实现、去查数据库字典。换一种写法:

List<Order> unpaidOrders = orderService.queryByStatus(userId, OrderStatus.UNPAID);
for (Order order : unpaidOrders) {
    if (order.isExpired()) {
        // ...
    }
}

代码几乎变成了一句话:"查出用户未支付的订单,遍历其中已过期的。"连那行"获取列表"的注释都不需要了。

几条我自己在实践中总结的命名习惯:

场景不推荐推荐
变量d、data、temp、list1elapsedDays、unpaidOrders
布尔值flag、statusisExpired、hasPermission、canRetry
魔法数字if (type == 3)if (type == AdType.VIDEO)
类型前缀strName、iCount、mListname、count、campaigns
方法handle()、process()、doIt()calculateDailyBudget()、sendWinNotice()

还有一点容易被忽略:同一个概念在整个项目里只用一个词。同一类操作,这里叫 fetch,那里叫 get,另一处又叫 retrieve,读代码的人就会怀疑它们之间是不是有什么区别。

命名之所以难,是因为它逼着你想清楚"这个东西到底是什么"。起不出好名字,往往说明设计本身还没想清楚。


二、关于函数:只做一件事

书里最有名的一句话大概是:函数应该只做一件事,做好这件事,只做这件事。

怎么判断函数是不是"只做了一件事"?我的经验是:如果你没法不用"和""然后"来描述它,那它就做了不止一件事。

比如下面这个方法,描述起来是"校验参数,然后计算价格,然后保存订单,然后发通知":

public void createOrder(OrderRequest request) {
    // 1. 参数校验
    if (request.getUserId() == null) { throw new IllegalArgumentException("userId 不能为空"); }
    if (request.getItems() == null || request.getItems().isEmpty()) { throw new IllegalArgumentException("商品不能为空"); }
    // ... 二十行校验

    // 2. 计算价格
    BigDecimal total = BigDecimal.ZERO;
    for (Item item : request.getItems()) {
        // ... 三十行优惠计算
    }

    // 3. 保存订单
    // ... 二十行

    // 4. 发送通知
    // ... 十五行
}

拆开之后,主流程就像一份目录:

public void createOrder(OrderRequest request) {
    validate(request);
    BigDecimal totalPrice = priceCalculator.calculate(request.getItems());
    Order order = orderRepository.save(Order.from(request, totalPrice));
    notificationService.notifyOrderCreated(order);
}

读代码的人先看清整体脉络,对哪一步感兴趣再点进去。每个小函数也更容易单独测试和复用。

参数越少越好

参数多了,调用方很容易传错顺序,可读性也会变差:

// 哪个是日预算?哪个是总预算?true 又是什么意思?
createCampaign("双十一大促", 1000, 50000, 3, true);

三个以上的参数,就该考虑封装成对象(Java 里可以用 Builder 或 record):

CampaignRequest request = CampaignRequest.builder()
        .name("双十一大促")
        .dailyBudget(1000)
        .totalBudget(50000)
        .frequencyCap(3)
        .build();
createCampaign(request);

另外,尽量避免布尔类型的"标志参数"。render(true) 本身就说明这个函数做了两件事,不如拆成 renderForPreview() 和 renderForPublish()。

不要有隐藏的副作用

一个叫 checkPassword() 的方法,如果顺手把用户 Session 也初始化了,那就是一个陷阱:调用者只想检查一下密码,却意外改变了系统状态。函数名应该如实说明它做的所有事情;如果名字装不下,就说明它该拆了。


三、关于注释:解释"为什么",而不是"做了什么"

好代码本身就是最好的注释。 这句话常常被误解成"不要写注释",其实书里想说的是:注释是对代码表达能力不足的弥补,先努力让代码自己说清楚,实在说不清再写注释。

不需要的注释

// 计数器加 1
count++;

// 如果用户是 VIP
if (user.getLevel() == 3) { ... }

第一种是废话;第二种可以通过更好的命名来消除:

if (user.isVip()) { ... }

还有一类最危险的注释:过时的注释。代码改了,注释没跟着改,它就会一本正经地误导后来的人。错误的注释比没有注释更糟。

值得写的注释

真正有价值的注释,解释的是代码无法表达的东西——为什么这么做:

// ADX 要求 100ms 内返回竞价响应,扣除网络往返后,内部处理只留 60ms,
// 所以这里不调用远程画像服务,只读本地缓存(宁可少一些人群命中,也不能超时)。
UserProfile profile = localProfileCache.getOrDefault(userId, UserProfile.EMPTY);
// 这里不能用 double:金额计算需要精确到分,浮点运算会产生舍入误差。
BigDecimal amount = price.multiply(BigDecimal.valueOf(quantity));

这类注释记录的是业务约束、技术取舍和踩过的坑,是代码本身无法承载的上下文。

被注释掉的代码,直接删掉

// oldPriceCalculator.calculate(items);
// if (useNewLogic) { ... }

每个看到这段代码的人都不敢删,因为"万一还有用呢",于是它就永远留在那里。Git 会记住一切,放心删掉。


四、其他几点收获

错误处理:别返回 null

List<Order> orders = orderService.findByUser(userId);
if (orders != null) {          // 每个调用方都要记得判空
    for (Order order : orders) { ... }
}

更好的做法:集合返回空集合(Collections.emptyList()),单个对象用 Optional 表达"可能不存在",异常情况直接抛出有意义的异常,而不是返回错误码让调用方层层判断。

童子军军规

书里引用了童子军的一条规则:离开营地时,让它比你来时更干净。

落到写代码上就是:每次改动代码,顺手把附近的代码整理得更好一点——改一个不清楚的变量名,拆一个过长的函数,删掉一段无用的注释。不需要专门安排"重构周",代码质量就是在这些小动作里一点点变好的。

测试是整洁代码的护城河

没有测试,重构就是冒险,久而久之大家就只敢"往上堆代码",不敢动已有的逻辑。有测试兜底,才敢放心地让代码变整洁。而测试代码本身也应该和业务代码一样整洁。


五、几点反思:不要变成教条

重读这本书,我也有一些不同的看法:

  1. 书写于 2008 年,部分示例和建议带着当时 Java 的时代痕迹。今天有了 Lambda、Stream、record、Optional 等特性,很多问题有了更简洁的解法;
  2. "函数越短越好"不是绝对的。为了短而过度拆分,会让读者在十几个两三行的小函数之间来回跳转,反而更难理解。拆分的目标是让每一层抽象清晰,而不是追求行数;
  3. 团队约定比个人偏好更重要。整洁的标准需要在团队里形成共识(代码规范、Code Review、静态检查工具),否则一个人的"整洁"可能是另一个人的"看不懂"。

说到底,这本书讲的不是一套必须严格遵守的规则,而是一种态度:对代码负责,对下一个读代码的人负责——而那个人,很可能就是半年后的自己。


写在最后

整洁的代码不是一次写出来的,而是一遍遍改出来的。Bob 大叔在书里把写代码比作写文章:先写出粗糙的初稿,再反复打磨。

愿我们都能写出让同事读起来舒服、让自己回头看时不想骂人的代码。