改善代码可读性的5种方法

本文最初发布于 byrayray.dev 网站，经原作者授权由 InfoQ 中文站翻译并分享。

在本文中，我会列举五条提高代码可读性的原则。这些原则是我在各种项目、团队和组织的实践中总结出来的经验。我希望大家可以从这篇文章中学到一些东西，从而提高代码的可读性。

太长不看版

总有人不喜欢从头到尾看完全文，而是想赶快看完重点，这里为此准备了太长不看版：

1. 重用会多次使用的内容。
2. 避免针对可读性和可维护性制定一个通行的解决方案。
3. 尽可能减小模块、类或组件的大小。
4. 为你的代码自动化执行一些规则和准则。
5. 就算你的团队只有你一个人，也要像是在多人团队中一样编写便于协作的代码。

1. 重用会多次使用的内容

大多数开发人员都知道 D.R.Y. 是什么意思（避免重复代码）。D.R.Y. 可以帮助你预防代码重复的问题。

为什么一个函数要写一遍又一遍呢？你应该只编写一次，然后在需要它的各个位置重复使用它。而且如果你需要更改它的代码，就只需要改动一处位置就可以了，用不着把修改好错误的版本复制粘贴到各个地方。

但请注意，D.R.Y. 原则会让你引入复杂性。因为到最后，事物被重用的次数会越来越多。

当你开始更改被多次重用的代码时，针对这部分代码编写测试的重要性就会充分体现出来了。

2. 避免针对可读性和可维护性制定通行的解决方案

可重用性、可读性和可维护性彼此之间既是朋友也是敌人。当你开始在自己的代码中践行 D.R.Y. 原则，你就会引入复杂性。当你引入复杂性时，可读性水平可能就会下降了。

因此，在构建功能时不要想着先做一个通行的解决方案。从简单入手是最好的！第一次尝试肯定没法做到尽善尽美。

通过多次迭代，你就可以在重用应用程序很多部分的同时，仍然保持不错的可读性和可维护性。

当你在拥有许多开发团队的组织中工作时，你的团队可能会分为内部人员和外部人员（例如自由职业者或顾问）。因此在这种情况下，人们会经常在不同组织之间来回切换。

在这些场景中，可读性和可维护性是成功的关键。让那些很可能随时离开团队的人员来制定通行的解决方案，并不是一个明智的选择。

在某些情况下，你的确需要通行方案，但这些方案必须做到很容易阅读和维护。

3. 尽可能减小模块、类或组件的大小

在为一款应用程序构建一些新功能时，你可能会在构建前作详细的规划。

最佳的解决方案肯定是能拆分成许多较小的模块、类或组件的。你想知道为什么吗？

因为小段代码更容易测试和维护。

想象一下，人们在现实中搭建高层建筑时，也是从一个个较小的单元开始拼装而成的，而不是一下子就把整幢大楼都造好，然后设法安装到地基上。当然了，例外也是有的。

大多数现代库和框架都分成了一些较小的构造块，而不是打包成单个文件。像 Angular、React 和 Vue 这样的 JavaScript 库和框架都采用了组件的概念。我认为他们的选择并不是无意识的结果。

4. 为你的代码自动化执行一些规则和准则

想要编写出可读和可维护的代码，一方面要关注的是代码的架构，另一方面则要关注代码的样式。

我想很多读者都经常会见到关于制表符或空格缩进的讨论。不过这里我不会讨论这个话题。无论你在团队中使用的是哪种方案，请确保所有团队成员都遵守它就行了。

最好的解决方案是，尽可能让这些代码样式规则和准则自动化。许多 IDE 都集成了这种功能，或者可以通过插件安装。

最简单的一种，也是支持多种语言和代码编辑器的方案是 editorconfig。只要添加一个.editorconfig，就可以应用这些规则。

你可以在这些文件中为你的项目调整许多设置。你也可以指定全局设置方案，或者为特定的语言指定设置。例如：

• 缩进样式：制表符或空格
• 引号类型：单引号或双引号
• 最大长度
• 字符集
• 还有更多……

下面是我在自己的一个项目中指定的配置：

# Editor configuration, see https://editorconfig.org
root = true
[*]
charset = utf-8
indent_style = space
indent_size = 2
insert_final_newline = true
trim_trailing_whitespace = true
[*.ts]
quote_type = single
[*.md]
max_line_length = off
trim_trailing_whitespace = false

网络上还有许多适用于某些特定语言的工具。对于 JavaScript 来说，我喜欢使用 Prettier，但你可能希望换一些不一样的工具。

不管怎样，只要参与项目的所有人都遵循相同的规则和准则，那么具体使用哪一种方案并不重要。

5. 就算只有你一个人，也要像在多人团队中一样编写代码

最后一点也是非常重要的，那就是永远都像在团队中一样编写便于协作的代码！

我可以想象，从未在团队中编写过代码的开发人员是很难理解这一条原则的。

可是如果你在一个人编写项目，就会很容易写出来很多只有你自己才能理解的代码（例如编写模糊不清的变量名、使用 2-3 个字符的变量名等等）。

应该试着像在团队中一样编写能方便他人理解的代码。想象一下，这就是说你的代码应该足够清晰明了，让其他人可以轻松理解。

你可以问一问朋友，或者在开发者社区中通过 Twitter 找什么人过来帮你检查代码的可读性，这是很简单的测试方法。我可以保证，你会得到自己意想不到的反馈。

不要担心负面反馈！你只要关注那些可以让你的代码对其他人更具可读性的反馈意见就行了。

你应该知道，可读代码与读起来略吃力的代码之间并没有很清晰的界限，不同人会在这个问题上有不同的看法。如果有人告诉你你的代码很难读，那也不要难过！你应该感谢对方的反馈意见。

小结

感谢大家的阅读！希望你从本文中起码能学到一点东西。如果你对提高代码可读性的方法有任何补充，请随时在评论中分享你的想法。

原文链接

Five Rules to Improve Code Readability