有个说法我很认同：

代码是写给人读的，只是顺便让机器执行。

代码的正确性当然重要，但如果一段代码除了作者谁都读不懂，那它就是个”定时炸弹”——三个月后连作者自己都读不懂了。

这一篇是”基础系列”的收尾，聊一个软性但极重要的话题：怎么写出整洁、可维护的代码。

命名：代码可读性的第一道关

命名的目标是：让人不读注释，光看名字就知道是什么意思。

几个原则：

  1. 用能表达意图的名字：d 不如 elapsedDays，process() 不如 calculateOrderTotal()
  2. 避免缩写：usrNm 不如 userName
  3. 布尔值用疑问句：isValid、hasPermission、isEmpty
  4. 方法名用动词：getUser、createOrder、validateInput

一个反例：

1
int d; // 天数

一个正例：

1
int elapsedDays;

好名字是免费的文档，不要吝啬。

函数：小而专一

一个函数应该只做一件事，并且要短。

判断标准：

  1. 函数是否小到”一眼能看完”？理想是 20 行以内
  2. 函数是否只做了一件事？如果描述它需要”和”字，就该拆
  3. 函数的嵌套层级是否太深？超过 3 层就该警惕

“抽取函数”是最常用也最有效的重构手段——把一段逻辑抽成一个有名字的函数，代码立刻清晰。

注释：能不用就不用

这个观点可能反直觉，但却是《代码整洁之道》的核心主张：

最好的注释，是能通过好命名和好结构”消灭”掉的注释。

因为注释会撒谎——代码改了，注释常常忘了改，结果注释和代码互相矛盾，比没注释更害人。

所以：

  • 能用命名说清楚的，别写注释
  • 注释应该解释”为什么“，而不是”是什么”（”是什么”看代码就懂了）
  • 删掉无意义的注释（比如 // 给 i 加 1 这种废话）

代码审查：最有效的质量手段

代码审查（Code Review）是提升代码质量和团队能力最有效的手段之一。

审查者应该看什么

  1. 正确性：逻辑对不对，边界条件考虑了吗
  2. 可读性：命名是否清晰、结构是否合理
  3. 安全性：有没有注入、越权、敏感信息泄露
  4. 性能：有没有明显的性能隐患
  5. 测试：有没有覆盖关键路径

审查的正确姿势

  • 对事不对人：评论代码，不评价人
  • 提问而不是命令：”这里是不是可以考虑 X？”比”你应该改成 X”更好
  • 关注重要问题：别纠结空格、命名风格这种小事（这些交给 lint 工具）

被审查者的心态

  • 别把 review 当找茬：review 是帮你成长，不是挑你毛病
  • 虚心但不盲从：有道理就改，有分歧就讨论

重构：持续改善而非大动干戈

重构不是”专门抽一个月把代码全部重写”，而是在日常开发中持续地、小步地改善。

什么时候该重构：

  • 同样的代码出现三次以上（三次法则，DRY 原则）
  • 函数太长、太复杂
  • 代码有”坏味道”（重复代码、超长函数、过大类、过长参数列表）

重构的保障是测试——有测试兜底，重构才安全。这也是前面强调单元测试的原因。

写在最后

我把”基础系列”从设计模式、数据结构、算法，一路写到整洁代码，其实贯穿了一个共同的东西：

对代码质量的敬畏。

技术会更新，框架会换代，但”把代码写清楚、把基础打扎实”这件事，永远不会过时。

这也正是我做这个博客、愿意在基础上花时间的初衷——慢即是快，扎扎实实把地基打好，才能走得更远。