如何编写易读的代码

作者: 康凯森

日期: 2016-12-03

分类: 笔记

提升编程水平最有效的方法就是反反复复地修改和推敲代码。

写出的代码能让人快速理解、轻松维护、容易扩展的程序员才是专业的程序员。

代码的写法应当使别人理解它所需的时间最小化。

如果有人真的完全理解了你的代码，他就应该能改动它、找出缺陷并且明白它是如何与你代码的其他部分交互的。

1 易读的变量命名

  • 把信息装进变量名中，为名字附带更多信息
  • 使用专业，信息含量更多的词
  • 使用更有表现力的词，英语中同义词很多，要准确使用
  • 避免空洞，泛泛的命名：tmp，foo，命名应当描述变量的目的或者它所承载的值
  • tmp适用于短期存在且临时性的变量
  • 用具体的名称代替抽象的名称
  • 如果你的变量是一个度量的话（如时间长度或者字节数），那么最好把名字带上它的单位。
  • 在小的作用域里可以使用短的名字
  • 利用名字的格式来传递含义，参考团队的编码规范
  • 确保变量的命名不被误解
  • 推荐用min和max来表示（包含）极限
  • 推荐用first和last来表示包含的范围
  • 推荐用begin和end来表示包含/排除范围

2 易读的代码布局

  • 使用一致的布局。
  • 用方法来整理不规则的东西。
  • 让相似的代码看上去相似。
  • 把相关的代码行分组，形成代码块。
  • 选一个有意义的顺序，始终一致地使用它。
  • 一致的风格比“正确”的风格更重要。

3 易读的注释

  • 注释的目的是尽量帮助读者了解得和作者一样多。
  • 不要为那些从代码本身就能快速推断的事实写注释。
  • 不要给不好的名字加注释——应该把名字改好。
  • 用注释来记录你对代码有价值的见解。
  • 为代码中的瑕疵写注释：TODO，FIXME等。
  • 把代码将来应该如何改动的想法用注释记录下来。
  • 给常量加注释。
  • 站在读者的角度用注释解释what? why?
  • 用注释公开可能的陷阱。
  • “全局观”注释：类之间如何交互，数据如何在整个系统中流动，以及入口点在哪里。
  • 总结性注释。
  • 可以做任何能帮助读者更容易理解代码的事。
  • 注释要言简意赅。
  • 注释应该紧凑。
  • 避免使用不明确的代词。
  • 润色粗糙的句子。
  • 精确地描述函数的行为。
  • 用输入/输出例子来说明特别的情况。
  • 声明代码的意图。
  • 采用信息含量高的词，用住专业的词来描述普遍的问题或解决方案。

如何养成写注释的习惯

1.不管你心里想什么，先把它写下来。

2.读一下这段注释，看看有没有什么地方可以改进。

3.不断改进。

4 易读的控制流

把条件、循环以及其他对控制流的改变做得越“自然”越好。运用一种方式使读者不用停下来重读你的代码。

相对于追求最小化代码行数，一个更好的度量方法是最小化人们理解它所需的时间。

当你对代码做改动时，从全新的角度审视它，把它作为一个整体来看待。

  • 条件语句中参数的顺序
  • 先处理掉简单的情况；先处理有趣的或者是可疑的情况。
  • 避免do/while循环。
  • 最小化嵌套。

5 易读的表达式

把你的超长表达式拆分成更容易理解的小块。

要小心“智能”的小代码段——它们往往在以后会让别人读起来感到困惑。

  • 拆分表达式最简单的方法就是引入一个额外的变量。
  • 不要滥用短路逻辑。
  • 简化复杂的逻辑。
  • 拆分巨大的表达式。

6 易读的变量使用

  • 减少变量。变量越多，就越难全部跟踪它们的动向。
  • 缩小变量的作用域。 变量的作用域越大，就需要跟踪它的动向越久。
  • 避免频繁改版变量。 变量改变得越频繁，就越难以跟踪它的当前值。
  • 不要使用没有价值的临时变量。
  • 减少中间结果。
  • 减少控制流变量。
  • 把变量的定义移到对它的使用之前。
  • 只写一次的变量更好。那些只设置一次值的变量（或者const、final、常量）使得代码更容易理解。

7 抽取不相关的子问题

所谓工程学就是关于把大问题拆分成小问题再把这些问题的解决方案放回一起。

积极地发现并抽取出不相关的子逻辑：

1.看看某个函数或代码块，问问你自己：这段代码高层次的目标是什么？

2.对于每一行代码，问一下：它是直接为了目标而工作吗？这段代码高层次的目标是什么呢？

3.如果足够的行数在解决不相关的子问题，抽取代码到独立的函数中。

  • 抽取纯工具的代码。
  • 抽取多用途的代码。
  • 抽取较通用的代码。
  • 简化已有的接口。
  • 按需重塑接口。

8 单一原则：一次只做好一件事

9 用自然语言将想法变成代码

如果你不能把一件事解释给你祖母听的话说明你还没有真正理解它。 阿尔伯特·爱因斯坦

1.像对着一个同事一样用自然语言描述代码要做什么。

2.注意描述中所用的关键词和短语。

3.写出与描述所匹配的代码。

如果你不能把问题说明白或者用词语来做设计，估计是缺少了什么东西或者什么东西缺少定义。把一个问题（或想法）变成语言真的可以让它更具体。

10 少写代码

知道什么时候不写代码可能对于一个程序员来讲是他所要学习的最重要的技巧。

你所写的每一行代码都是要测试和维护的。

通过重用库或者减少功能，你可以节省时间并且让你的代码库保持精简节约。

最好读的代码就是没有代码。

  • 明确需求并尽可能减少需求。
  • 删除没用的代码。
  • 熟悉API和经典的第三方库。

11 易读的测试

大多数测试的基本内容都能精练成“对于这样的输入/情形，期望有这样的行为/输出”。并且很多时候这个目的可以用一行代码来表达。

  • 让错误消息具有可读性。
  • 选择好的测试输入。好的输入应该能彻底地测试代码，但是它们也应该很简单易读。
  • 又简单又能完成工作的测试值更好。
  • 为测试函数命名。
  • 写出易于测试的代码：避免使用全局变量；避免写对外部组件有大量依赖的代码；避免代码有不确定的行为。

12 参考资料

本文是《编写可读代码的艺术》的笔记。

《OLAP 性能优化指南》欢迎 Star&共建

《OLAP 性能优化指南》

欢迎关注微信公众号

康凯森