编写可读代码的艺术

|

《编写可读代码的艺术》，这本书有一些有趣的地方，可以观摩观摩。

把信息塞进名字中

图0：编写可读代码的艺术

  1. 避免空泛的名字，像tmp和retval，除非使用它们有特殊的理由。
  2. 使用具体的名字来更细致地描述事物——ServerCanStart()这个名字就比CanListenOnPort更不清楚。
  3. 给变量名带上重要的细节——例如，在值为毫秒的变量后面加上_ms。
  4. 为作用域大的名字采用更长的名字——不要用让人费解的一个或两个字母的名字来命名在几屏之间都可见的变量。对于只存在于几行之间的变量用短一点的名字更好。
  5. 有目的的使用大小写、下划线等——例如，你可以在类成员和局部变量后面加上“_”来区分它们。

不会误解的名字是最好的名字

图1：编写可读代码的艺术

  1. 当要定义一个值的上限或下限时，max_和min_是很好的前缀。对于包含的范围，first和last是最好的选择。对于包含/排除范围，begin和end是最好的选择，因为它们最常用。
  2. 当为布尔值命名时，使用is和has这样的词来明确表示它是个布尔值，避免使用反义的词(例如disable_ssl)。
  3. 要小心用户对特定词的期望。例如，用户会期望get()或者size()是轻量的方法。

大家都愿意读有美感的代码

图2：编写可读代码的艺术

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

什么地方不需要注释

图3：编写可读代码的艺术

  1. 能从代码本身中迅速地推断的事实。
  2. 用来粉饰烂代码（例如蹩脚的函数名）的“拐杖式注释”——应该把代码改好。

你应该记录下来的想法

图4：编写可读代码的艺术

  1. 对于为什么代码写成这样而不是那样的内在理由（“指导性批注”）。
  2. 代码中的缺陷，使用像TODO：或者XXX：这样的标记。
  3. 常量背后的故事，为什么是这个值。

站在读者的立场上思考

图5：编写可读代码的艺术

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

把更多的信息装入更小的空间里

图6：编写可读代码的艺术

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

让代码的控制流更易读

图7：编写可读代码的艺术

  1. 在写一个比较时，把改变的值写在左边，并且把更稳定的值写在右边更好一些。
  2. 你也可以重新排列if/else语句中的语句块。通常来讲，先处理正确的/简单的/有趣的情况。有时这些准则会冲突，但是当不冲突时，这是要遵循的经验法则。
  3. 三目运算符必须在结构非常简单的情况下使用。
  4. 嵌套的代码块需要更加集中精力去理解。应该把它们改写成更加“线性”的代码来避免深嵌套。
  5. 通常来讲提早返回可以减少嵌套并让代码整洁。“保护语句”（在函数顶部处理简单的情况时）尤其有用。

减少变量的数量和让它们尽量“轻量级”来让代码更有可读性

图8：编写可读代码的艺术

  1. 减少变量，即那些妨碍的变量。
  2. 减小每个变量的作用域，越小越好。
  3. 只写一次的变量更好。那些只设置一次值的变量（或者const、final、常量）使得代码更容易理解。

你也许感兴趣的：

发表回复

您的电子邮箱地址不会被公开。 必填项已用 * 标注