为什么整洁代码是反人性的：三个让代码更好读的实践

那些看起来优雅的代码，往往是违背程序员直觉和本能的结果。

从业时间长了，会发现一个有趣的现象：新手程序员写的代码往往非常“直接”，想到哪就写到哪，一个函数动辄几百行，变量名随性而起，只要程序能跑起来就算成功。

工作几年后，开发者开始有意识地去讲究设计模式，追求代码的优雅，关注命名规范。

而再往后，代码风格反而会回归“平淡”——追求简单、直接，甚至看起来有些“笨拙”。

这并非是一种退步，恰恰是领悟了编程的本质：代码首先是写给人看的，其次才是让机器执行的。

今天就来聊聊三个能让代码变得更易读、更易维护的习惯。每一个习惯都或多或少地“反人性”，需要我们刻意练习才能内化。

1. 命名：告别惰性的第一道坎

人类天生倾向于节省认知能量，写代码时也不例外。脑海里第一时间冒出的变量名往往是 data、list、temp、result 这类万金油词汇。

然而，这其实是在给未来的自己埋坑。三个月后回看，data 到底装的是用户信息、订单列表还是系统配置？你很可能已经想不起来了。

一个实用的建议是： 养成习惯，让变量名至少清晰地表达出“它是什么”以及“它用来做什么”。

• data → user_profile_data
• list → pending_order_list
• temp → temp_celsius

多敲几个字符，换来的是日后调试和阅读时数小时的精力和几根头发的保存，这无疑是笔划算的买卖。

函数命名同理。handleData() 是个模糊的“黑洞”，看了等于没看。而 validateUserEmail() 则一目了然——只看函数名就能大致猜出其功能和边界，甚至无需深入阅读其实现。

一个简单的自检标准： 如果你的函数名还需要额外的注释来解释它做了什么，那么这个命名很可能就不合格。

2. 函数：坚守“单一职责”的信仰

在编码过程中，很容易产生“顺手就把这个也做了”的想法。于是，一个函数里可能混杂了参数校验、数据库查询、业务计算、发送通知、记录日志等多种职责。一气呵成写完，成就感满满。

但这种“爽快”是有代价的。这种巨型函数难以维护：修改一个逻辑可能无意中影响其他无关功能；想复用其中的某段代码却发现无法剥离；出现 Bug 时，需要花费大量时间定位问题究竟出在哪个环节。

请将“一个函数只做一件事”作为编码信仰。

如何判断是不是“一件事”？尝试用一句简单的话来描述这个函数。如果能清晰描述，那就是一件事。

• “根据用户ID查询用户信息” ✅ (这是一件事)
• “查询用户信息并发送欢迎邮件” ❌ (这明显是两件事)

将大函数拆分为若干小函数后，每个函数的逻辑都变得更纯粹、更清晰。修改功能的影响范围缩小了，单元测试也更容易编写。不要担心函数数量过多，大量实践证明：短小精悍的函数远比冗长复杂的函数更容易阅读和理解。

3. 注释：解释“为什么”，而非复述“是什么”

代码中充斥着大量无效的注释，它们就像是代码的“噪声”。

例如：i++ // 计数器加1。这类注释完全是多余的，因为代码本身已经清晰地表达了“是什么”。删除它们，代码反而更干净。

真正有价值的注释，在于解释代码背后的“原因”和“意图”。

为什么这里选择使用缓存而不是直接查询数据库？为什么这个阈值被设定为 10 而不是 20？为什么这段代码采用了看似迂回的写法？

建议只在以下三种情况下编写注释：

1. 交代业务背景： 解释这段代码存在的业务原因或特殊上下文。
2. 说明非常规做法： 解释为何没有采用更常规或更直观的实现方式。
3. 标记已知的“坑”： 警示他人此处有需要注意的陷阱或限制。

除此之外，请相信代码的自述能力，努力让代码自己“说话”。

写在最后

写出整洁、可读的代码，没有捷径可言。它不是一个纯粹的技术问题，而是一个关于自律和习惯的问题。每一次我们克服本能，为一个变量认真命名、将一个庞杂的函数拆分、写下一条解释“为什么”的注释，都是向着更好代码迈进的一步。

当这些习惯内化后，你会发现：修复 Bug 时不再心慌意乱，同事接手你的代码时少了几分抱怨，甚至半年后回顾自己的旧代码，依然能快速理解其逻辑。

对于追求长期价值的开发者而言，这就是最重要的回报。这些关于命名、函数设计和代码注释的原则，是构成坚实 编程基础 的重要组成部分。如果你想与更多开发者交流这些实践心得，欢迎来 云栈社区 一起探讨。