如何使自己写的代码易读易懂？

news2024/11/8 12:18:00

〓● 如果代码可读性不佳、不容易理解，可能造成如下问题：

〓❏ 其他工程师浪费时间解读它；

〓❏ 误解导致引入缺陷；

〓❏ 其他工程师修改时破坏代码。

〓● 提高代码可读性，有时候可能使其变得更为冗长、占用更多的代码行数。这往往是有价值的权衡。

〓● 提高代码可读性往往需要同理心——想象其他人可能觉得困惑的情况。

〓● 现实生活中的场景各不相同，通常有各自面临的挑战。编写易于理解的代码几乎总是需要应用常识和判断力。

编写易于理解的代码

实现代码可读性最为常见、有效的技术打下坚实的基础。但需要牢记的是，现实生活中的每个场景都不相同，有各自的考虑因素，因此常识的运用和良好的判断力都是必不可少的。

1　使用描述性名称

名称是唯一标识事物所必需的，它们也往往能提供对事物概念的简单总结。“烤箱”这个词是某个厨房用具的唯一标识，但也明显地暗示了这件用具的用途：烧烤食物。如果我们坚持用“对象A”来指代一台烤箱，就很容易忘记“对象A”是什么东西，起什么作用。

在代码中命名不同事物也适用相同的原则。名称是唯一标识类、函数和变量等对象所必需的。但我们对事物的命名也提供了很好的机会，可以通过确保以不言自明的方式指代事物，使代码更易于理解。

2　适当使用注释

代码中的注释或文档可以起到多种作用，如：

〓● 解释代码完成的是什么；

〓● 解释代码为什么完成这些工作；

〓● 提供其他信息，如使用指南。

本节将集中说明前两个作用：使用注释解释“什么”和“为什么”。使用说明等其他信息通常组成代码契约的一部分，这些已在第3章讨论过。

概述大块代码（如一个类）作用的高层注释常常很有用。然而，在较低层次的代码细节上，解释代码作用的注释往往不是提高代码可读性的最有效手段。

在代码行级别的作用上，使用描述性名称、编写质量良好的代码应该是不言自明的。如果我们需要为代码添加许多底层注释以解释它的作用，那么这很可能是代码可读性不理想的迹象。相反，解释代码为什么存在或提供更多背景信息的注释往往相当有用，因为只用代码不总是能够说明这些。

3　不要执着于代码行数

一般来说，代码库中的代码行数越少越好。代码通常需要一定的持续维护，代码行数越多，有时就意味着代码过于复杂，或者没有重用现有的解决方案。较多的代码还会增加工程师的认知负荷，因为阅读量显然更大了。

工程师有时会在这方面走极端，认为最大限度地减少代码行数比代码质量的其他因素更重要。他们有时会抱怨，所谓的“代码质量改善”将3行代码变成10行代码，因此产生的代码更差了。

但应该牢记的是，代码行数只是我们真正关心的事情的一个替代指标，与大部分替代指标一样，这是个有用的指导原则，但并非铁律。我们真正关心的是确保代码：

〓● 容易理解；

〓● 不容易受到误解；

〓● 不容易在无意中遭到破坏。

并不是所有代码都是一样的：与10行（甚至20行）易于理解的代码相比，1行极其难以理解的代码更容易降低代码质量。5.3.1节和5.3.2节用例子阐述了这一点。

4　坚持一致的编程风格

在我们造句的时候，必须遵循某些规则，才能写出语法正确的句子。此外，我们应该遵循一些其他风格上的指南，以确保我们的句子容易理解。

举个例子，想象一下我们要写段关于“软件即服务”（Software as a service）的文字。通常，如果一个首字母缩略词包含“a”或“as”等单词，那么这些单词应该用小写字母形式。因此，人们最熟悉的“软件即服务”缩写为SaaS。如果我们将这个缩略词写成SAAS，阅读文档的人可能会误以为我们指的是其他事物，因为那不是他们预期中的“软件即服务”的缩写。

这也同样适用于代码。语言的语法和编译器规定了允许的写法（有点像语法规则），但在工程师编写代码时，我们对于采用的风格惯例有很大的自由度。

5　避免深嵌套代码

典型的代码由相互嵌套的块组成，如：

〓● 函数定义一个调用时运行的代码块；

〓● if语句定义条件为真时运行的代码块；

〓● for循环定义每次迭代时运行的代码块。

图6　使函数调用易于理解

如果函数命名得当，它的作用应该是显而易见的，但即便有了这样的函数，如果参数的目的和作用不明，函数调用也很可能无法理解。1说明了控制流逻辑（如if语句和for循环）造成代码块相互嵌套的情况。代码中的指定逻辑通常有不止一种构造方法。有些形式可能造成许多代码块嵌套，而其他方法可能几乎不会造成任何嵌套。考虑代码结构对可读性的影响是很重要的。