如何编写可读性高的代码

2019-08-11

写代码不要只顾自己爽，也要兼顾代码的可读性。程序员之间的相互尊重体现在他们所写的代码中，他们对工作和职业的尊重也体现在代码上。

代码即架构。代码写的烂，不注重可读性，队友看了会问候你，估计也没人愿意接手你的烂摊子，隔一段时间后再看你也会骂娘。

从成本角度看，软件成本由开发成本和维护成本组成，而往往维护成本要远高于开发成本，这其中耗费的主要成本就是由于理解代码和修改代码造成的。

《编写可读代码的艺术》这本书主题是让代码变得更容易理解，确切的说，使别人用最短的时间理解你的代码。

对代码有追求的工程师都应该翻翻这本书。

摘录

一、表面层次的改进

  1. 把信息装到名字里。一个变量名就像是一个小小的注释，读者只通过名字就可以获得大量信息
    • 选择专业的单词。比如 get 不如 fetch 具体（由上下文决定）
    • 避免空泛的名字。比如 temp 和 i，除非有特殊的理由
    • 使用具体的名字代替抽象的名字
    • 给变量名带上重要的细节。比如在值为秒的变量后加上 second
    • 为作用域大的名字采用更长的名字。在小的作用域可以使用短名字，不要使用项目特有的缩写
    • 利用名字的格式来传递含义。比如有目的地使用大小写、下划线等区分变量，视团队规范而定
  2. 不会误解的名字是最好的名字。多审视名字是否会造成误解
    • 很多英语单词在用来编程时是多义的，例如 filter、length、limit
    • 当要定义一个值的上限和下限时，max 和 min 是很好的前缀
    • 对于包含的范围，first 和 last 是好的选择
    • 对于包含或排除范围，begin 和 end 很常用
    • 为布尔值命名时，使用 is 或 has 这样的词来明确表示它是个布尔值，避免使用反义的词（例如 disable_ssl）
    • 要小心读者对特定词的期望。例如，读者会期望 get 或 size 是轻量的方法
  3. 整洁的代码格式
    • 使用一致的风格
    • 把代码按列对齐可以让代码更容易浏览
    • 选择一个有意义的顺序，并始终用这样的顺序。比如按字母顺序
    • 用空行把大块代码分成逻辑上的段落
    • 与团队保持一致的风格比“正确”的风格更重要
  4. 该写什么样的注释。注释的目的是尽量帮助读者了解得和作者一样多
    • 什么时候不需要写注释。阅读注释会占用阅读真实代码的时间，注释也会占用屏幕上的空间，所以不要写没价值的注释
      • 能从代码本身迅速推断的事实
      • 不要给不好的名字加注释，而是应该把名字改好。好名字比好注释更重要
    • 用代码记录你的想法
      • 为什么代码要写成这样而不是那样的内在理由
      • 代码中的缺陷，使用类似 TODO 这样的标记
      • 常量为什么要用这个值
    • 站在读者角度，去想象他们需要知道什么
      • 为普通读者意料之外的行为加上注释
      • 在文件或类级别上使用“全局观”注释来解释所有部分是如何一起工作的
      • 用注释来总结代码块，使读者不致迷失在细节中
  5. 写出言简意赅的注释。注释应当精确而紧凑
    • 避免使用 it 和 this 这种可能指代多个事物的词
    • 尽量精确描述函数的行为
    • 在注释中用精心挑选的输入输出例子进行说明
    • 声明代码的高层次意图，而非明显的细节
    • 用嵌入的注释来解释难以理解的函数参数
    • 用含义丰富的词来使注释简洁

二、简化循环与逻辑

  1. 把控制流变得易读。越自然越好
    • 写比较语句时，改变的值写在左边，更稳定的值写在右边
    • 重新排列条件判断语句中的语句块，优先处理正确的、简单的和有趣的情况
    • 避免使用复杂的三目运算符、do while循环和 goto 这种会让代码可读性变差的编程结构
    • 避免深嵌套的代码。应该改成更加线性的代码
    • 使用保护语句提早返回可以减少嵌套
  2. 拆分超长的表达式。大多数人只能同时考虑 3-4 件事情
    • 引入解释变量
    • 使用德摩根定理优化逻辑表达式
  3. 变量和可读性
    • 减少变量。尤其是不能改进可读性的临时变量
    • 缩小变量的作用域。尽量避免全局变量
    • 只写一次的变量更好。final类型、常量使得代码更容易理解。操作一个变量的地方越多，越难确定它的当前值

三、重新组织你的代码

  1. 主动抽取不相关的子问题。把一般代码和项目专有的代码分开。这样可以使你关注小而定义良好的问题
  2. 一次只做一件事。尝试把难读的代码的所有任务列出来，部分任务可拆成单独的函数或类，或者成为函数中的逻辑段落
  3. 采用橡皮鸭调试法，把想法变成代码。用自然语言描述程序然后用这个描述来帮助写出更自然的代码
  4. 少写代码。代码需要开发、测试、写文档和维护，代码越多，债务越多，维护越麻烦
    • 从项目中清除不必要功能，不要过度设计
    • 重新考虑需求，解决当前版本最简单的问题，只要能完成工作即可
    • 经常性通读标准库的 API ，保持对它们的熟悉程度，多重用它们

四、可读代码与测试

  1. 最好每个测试的输入和输出可以用一行代码来描述
  2. 如果测试失败了，它所发出的错误信息能让你容易跟踪并修复这个问题
  3. 使用最简单的并且能够完整运用代码的测试输入
  4. 给测试函数取一个有完整描述性的文字，以使每个测试所测到东西很明确
  5. 要易于改动和增加新的测试
  6. 不要对测试关注过度，它应该是项目的一个方面而不是主导。比如不要追求 100% 的测试覆盖率
Post TOC
Comments
Write a Comment
△