读《代码整洁之道》有感
《代码整洁之道》
读《代码整洁之道》有感
代码是写给人看的,只是顺便能被机器执行。 —— 《计算机程序的构造和解释》(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、list1 | elapsedDays、unpaidOrders |
| 布尔值 | flag、status | isExpired、hasPermission、canRetry |
| 魔法数字 | if (type == 3) | if (type == AdType.VIDEO) |
| 类型前缀 | strName、iCount、mList | name、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 表达"可能不存在",异常情况直接抛出有意义的异常,而不是返回错误码让调用方层层判断。
童子军军规
书里引用了童子军的一条规则:离开营地时,让它比你来时更干净。
落到写代码上就是:每次改动代码,顺手把附近的代码整理得更好一点——改一个不清楚的变量名,拆一个过长的函数,删掉一段无用的注释。不需要专门安排"重构周",代码质量就是在这些小动作里一点点变好的。
测试是整洁代码的护城河
没有测试,重构就是冒险,久而久之大家就只敢"往上堆代码",不敢动已有的逻辑。有测试兜底,才敢放心地让代码变整洁。而测试代码本身也应该和业务代码一样整洁。
五、几点反思:不要变成教条
重读这本书,我也有一些不同的看法:
- 书写于 2008 年,部分示例和建议带着当时 Java 的时代痕迹。今天有了 Lambda、Stream、
record、Optional等特性,很多问题有了更简洁的解法; - "函数越短越好"不是绝对的。为了短而过度拆分,会让读者在十几个两三行的小函数之间来回跳转,反而更难理解。拆分的目标是让每一层抽象清晰,而不是追求行数;
- 团队约定比个人偏好更重要。整洁的标准需要在团队里形成共识(代码规范、Code Review、静态检查工具),否则一个人的"整洁"可能是另一个人的"看不懂"。
说到底,这本书讲的不是一套必须严格遵守的规则,而是一种态度:对代码负责,对下一个读代码的人负责——而那个人,很可能就是半年后的自己。
写在最后
整洁的代码不是一次写出来的,而是一遍遍改出来的。Bob 大叔在书里把写代码比作写文章:先写出粗糙的初稿,再反复打磨。
愿我们都能写出让同事读起来舒服、让自己回头看时不想骂人的代码。