禅道博客

分享专业技术知识,文章内容干货满满

《编写可读代码的艺术》1-8章总结

2023-12-21 15:22:52
刘刚
原创 612
摘要:代码应当易于理解、把信息装到名字里、命名规范、不被误解、具有审美……这些编写可读代码的艺术,你都了解吗?

1 代码应当易于理解

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

2 把信息装到名字里

  • 使用专业的单词——例如,不用 Get,而用 Fetch 或者 Download 可能会更好。
  • 避免空泛的名字,比如 tmp 和 retval,除非有特殊理由。
  • 使用具体的名字来更细致的描述事物。
  • 给变量名带上重要的细节——比如在表示毫秒的变量后面加上 _ms,或者在还需要转义的未处理的变量前面加上 raw_ 。
  • 为作用域大的变量采用更长的名字。
  • 有目的地使用大小写、下划线等。

3 不会误解的名字

不会误解的名字是最好的名字——阅读你代码的人应该理解你的本意,并且不会有其他的理解。

在你决定使用一个名字以前,要吹毛求疵一点,来想象一下你的名字会被误解成什么。最好的名字是不会被误解的。

当要定义一个值的上限或下限时,max_ 和 min_ 是很好的前缀。对于包含的范围,first 和 last 是好的选择。对于包含/排除范围,begin 和 end 是最好的选择。

当为布尔值命名时,使用 is 和 has 这样的词来明确表示它是个布尔值,避免使用反义的词(例如 disable_ssl)。

要小心用户对特定词的期望。例如,用户会期望 get() 或者 size() 是轻量的方法。

4 审美

  • 如果多个代码块做相似的事情,尝试让它们有同样的剪影。
  • 把代码按“列”对齐可以让代码更容易浏览。
  • 如果在一段代码中提到A、B和C,那么不要在另一段中说B、C和A。选择一个有意义的顺序,并且始终用这样的顺序。
  • 用空行来把大块代码分成逻辑上的“段落”。

5 该写什么样的注释

注释的目的是帮助读者去了解作者在写代码时已经知道的那些事情。


什么地方不需要注释:

  • 能从代码本身中迅速的推断的事实。
  • 用来粉饰烂代码的注释——应该把代码写好。

你应该记录下来的想法包括:

  • 对于为什么代码写成这样而不是那样的内在理由。
  • 代码中的缺陷,使用像 TODO: 或者 XXX: 这样的标记。
  • 常量背后的故事,为什么是这个值。

站在读者的立场上思考:

  • 预料到代码中哪些部分会让读者说:“啊?”并且给它们加上注释。
  • 为普通读者意料之外的行为加上注释。
  • 在文件/类的级别上使用“全局观”注释来解释所有的部分是如何一起工作的。
  • 用注释来总结代码块,使读者不致迷失在细节中。

6 写出言简意赅的注释

  • 当像“it” 和“this”这样的代词可能代指多个事物时,避免使用它们。
  • 尽量精确的描述函数的行为。
  • 在注释中用精心挑选的输入/输出例子进行说明。
  • 声明代码的高层次意图,而非明显的细节。
  • 用嵌入的注释(如 Function(/* arg=*/…))来解释难以理解的函数参数。
  • 用含义丰富的词来使注释简洁。

7 把控制流变得易读

在写一个比较时,把改变的值写在左边并且把更稳定的值写在右边更好一些。

你也可以重新排列 if/else 语句中的语句块。通常来讲,先处理正确的/简单的/有趣的情况。

某些编程结构,如三目运算符(:?)、do/while 循环,以及 goto 经常会导致代码的可读性变差。最好不要使用它们,因为总是有更整洁的代替方式。

嵌套的代码块需要更加集中精力去理解。每层新的嵌套都需要读者来把更多的上下文“压入栈”。应该把它们改写成更加“线性”的代码来避免深嵌套。

通常来讲提早返回可以减少嵌套并让代码整洁。“保护语句”(在函数顶部处理简单的情况时)尤其有用。

8 拆分超长的表达式

一个简单的技术是引入‘解释变量’来代表较长的子表达式。这种方式有三个好处:

  • 它把巨大的表达式拆成小段。
  • 它通过用简单的名字描述子表达式来让代码文档化。
  • 它帮助读者识别代码中的主要概念。

另一个技术是用德摩根定理来操作逻辑表达式——这个技术有时可以把布尔表达式用更整洁的方式重写(例如 if(!(a && !b)) 变成 if(!a || b))。

暂时没有记录
评论通过审核后显示。