编写高可读代码的十个实践

译者：白玉堂

作者：Jason McCreary

我已经写了20年的代码，曾经和17个团队用不同的编程语言创建了上百个项目。这些项目包括几乎所有的软件类型，从个人博客，到支撑3000个请求/秒的接口，再到顶级的销售App。

从这些经历中，结合我看过的书，我越来越清晰的认识到编程中最重要的事：可读性(readability)。

表面上看，可读性可能是主观的，有时又受到编程语言、代码库和团队的影响。但是当你深入观察，在代码中的的一些核心元素让他们更具有可读性。

很多的编程者只关心机器，只要代码能够运行，别的都不重要了。然而一种普遍的辩解认为，这会把我们做的事中所有的人为因素都消灭掉了。

最近的几个月，我致力于提取这些因素，总结了10个实践，目的是编写能够提高代码可读性和降低复杂度的代码。我已经详细的写出来并配上实例代码在BaseCode.

但是不幸的是，很多反驳者认为这些太基础、微不足道。但是我向你保证，我遇到的每一个坏代码都没有运用这些实践，并且每个好的代码都有一个实践例子，如果不是很多的话

格式化 Formatting

很多精力浪费在格式化了，缩进符号使用制表符还是空格，函数或代码结构体开启的花括号是紧跟其后还是另起一行？你会意识到格式化并不是重要的事情。接受一个格式化标准，应用到代码库，并设置自动格式化。然后你才能把精力重新放在真正写代码上。

无用代码 Dead code

所有的注释块、没有使用的变量和从没有真正执行的代码都是会腐烂的。他们实际上告诉阅读代码的人：我不关心这些代码。所以就开始腐烂了。随着时间过去，这些无用的代码将会杀死你的代码库，这就是经典的《破窗理论》注：此理论认为环境中的不良现象如果被放任存在，会诱使人们仿效，甚至变本加厉。

你必须找到并毁掉无用代码，虽然这不需要成为你的优先考虑点，但是你要始终是一名童子军。注：引申美国童军的座右铭--“时刻准备着”，随时随手去除无用代码

嵌套代码 Nested code

​

image.png

​

配图为译者选自网络

几乎所有的代码都是业务逻辑，我们编写代码去判断、迭代和计算。这些经常导致循环或分支有着非常深的代码块嵌套。虽然这可能比较容易被计算机顺序执行，但是这样做可能会让人阅读起来费劲，这些代码越发复杂和不可读。可以通过“卫语句”、尽早返回，或函数式编程方面来解决多层嵌套代码的问题。

使用对象 Using objects

尽管当下是面向对象编程的时代，我们还是有基本类型变量偏执注：意为太喜欢用基本类型的变量。我们发现这种偏执体现在过长的参数列表、数据团、自定义的数组(字典)结构，这些都可以重构为对象。这么做，不仅可以让数据结构更正式，还为那些包含原始数据的重复逻辑提供了一个可被追踪的“根”或变量来源。

大代码块 Big Blocks

代码可以超过一个临界线，我并不执着于一个死板的数字。当你确定你有一个大的代码块的时候，这是你识别、重组和重构代码的机会。这个简单的过程让你确定上下文和对代码的抽象水平，继而你可以正确区分职责，并把代码重构成更加可读和简易化的代码快。

命名 Naming

毫无疑问，命名很难。但只因为我们让他变困难。在编程中，有一些很有效的小建议，包括延迟命名。不要因为命名这件事而卡住进度，就继续写代码吧。如果你必须命名一个变量一个句子，仍旧继续写代码。我保证在你完成特性代码或工作时，一个更好的名字一定会自己出现。

删除注释 Removing Comments

这个实践对我来说是原始规则改变者，这也是让我开始关注代码可读性的原因。尽管我努力解释，但是仍然只有少一个人因为这个而讨厌我。他们有举了一个例子来说明注释是完全有必要的。诚然，当哈勃望远镜遥测系统必须通过返回687与传统适配器连接以获取未知读数时，可能需要与注释进行沟通。但是对于其他一切，你应该挑战你自己重写代码直到代码不需要特别的注释说明。注：代码应该具有自解释功能，好的代码不需要特别的说明，如果非要添加一些说明才看得懂代码要表达说明，可能你方向已经走偏了，你要重构代码，而不是给代码加说明。另外要区别于Java注解、PHPDoc文档

合理返回 Reasonable Returns

我们返回了很奇怪的值，特别是边界条件，比如 -1, 687，null 。继而，又写了好多代码来处理这些奇怪的值。实际上，null 的发明者称其为 10亿美元的错误，你应该致力于返回一个更合理的值。理想情况下，即便是消极不期待的方向，也能让调用代码继续执行。如果有真正特殊的情况，用用好的方式来传达，而不是用null。

"三" 规则 Rule of Three

想象一下，有一系列数字，我向你提供了数字 2 并问：下一个是什么？可能是 3 或 4，也可能是 1 或 2.1，实际上，你也不知道。然后，我提供了另一个数字：2, 4 并问：下一个是什么？可能是 6 或 8 或 16。这次，尽管我们增加了一些信心，但是我们还是不确定。现在我提供了另一个数字：2， 4， 16 并问：下一个是什么？现在有三个数字，我们程序员的大脑会看到是平方并确定下一个数字是 256，这就是3规则。

这个例子演示了“如果不能引导我们正确的思路，我们不应该预先确定抽象和设计”。“三”规则用延迟来打消了我们和重复斗争的想法，直到我们有更多的数据可以做出正确的决定。用Sandi Metz的话说，“重复比错误的抽象便宜得多。”注：就是不要过早的抽象设计，因为可能一两次的重复并不能正确的发现共性（但是错误的抽象代价就大了），可以等等遇到足够多重复情况能清晰的帮助你考虑正确的抽象设计。

对称 Symmetry

现在是最后一个，一个能给任意代码像诗一样的可读性的实践：对称。这是引用自 Kent Beck 的《Implementation Patterns》

Symmetry in code is where the same idea is expressed the same way everywhere it appears. 代码中的对称性是在任何出现的地方都能用相同的方式表达相同的想法。

这说起来容易做起来难啊，对称更体现出了编写创造性的一面。他是其他事件的基础：命名、结构、对象、模式。他还可能因开发语言、代码库、和团队不同而异。因此，你可以在日常事件来达到这个目标。然后，一旦你开始把对称性应用到你的代码里，一个简约纯粹的形式就会出现并且代码会很快成型。

​

DnTrL7PX4AAsB-C.jpeg

​

译者后记

写好代码只有一个途径，那就是看更多好代码。github有世界上数不清的顶尖的程序员、软件开发者，甚至有 阿波罗的源代码。阅读代码是最好的途径。

一个观念性问题是：代码是给人看的，不是机器。这是我最大的感受。所以昨天用了两个小时翻译了那篇文章。代码的可读性影响后期维护   质量，影响扩展。影响效率。写出更好的代码，是让人心情愉悦的事情。

扩展阅读

• 程序员提高编程能力万无一失的办法
• 为什么高级程序员写的代码都是傻瓜式的？
• 如何重构箭头型代码？
• 方法总是有-统一PHP编码风格工具有N种
• 前段时间看到的一个比较干净的代码 >> https://github.com/youzan/open-sdk-php