如何编写可读性代码

编写可读性代码

作者：极链科技 汤红燕

什么叫可读性代码？

简单来说，就是易于理解、耗脑时间少、可维护性较高的代码。

编写可读性代码

把信息装到名字里（一个好的名字可以承载很多信息）

1. 选择专业的词（避免“空洞”）

比如函数 getUserInfo( ) 是用来获取用户信息，但是，是从接口中获取的信息呢？还是在页面已经暴露的信息？看到的时候就会有疑问。

命名的时候，如果是从互联网中获得，可以使用fetchUserInfo( )来表示。

2. 找到更有表现力的词(更清晰、精确)

比如：search 和 find 区别 ，再可以类似于表格数据的筛选， 可以考虑用更准确的词汇去表示。

避免使用像 tmp 和 retval 这样泛泛的名字。

3. 使用具体的名字更细致地描述事物

对于一个变量包含十六进制字符串，命名为 let id，但是为何不命名成 let hex_id?

如果你的变量时一个度量值的话，最好让名字带上它的单位。

4. 名字应该有多长

在编写代码取名的时候总会有一些疑问，我的定义名称该多长才合适？可以遵循以下几点：

l 小作用域里可以使用短的名字；

l 首字母缩略词和缩写（当然是在成员能看懂的情况下 TBColor -> TextBackgroundColor）；

l 丢掉没用的词（no-padding-all -> no-padding）；

l 利用名字的格式来传递含义（比如所有的class 是class-name, id 是 id_id）；

不会让人误解的名字

常用的 filter() 命名，如果新同学看到，可能会产生疑问，这是过滤掉满足要求的值呢还是不满足要求的？

为了便于处理以上情况，有以下几点建议：

l 使用 min 和 max 来表示（包含）极限

l 使用 first 和 last 来表示包含的范围

l 使用 begin 和 end 来表示包含/排除范围

l 给布尔值命名

对于语句 bool read_password = true 是我们已经读取密码，还是我们需要读取密码?

这时候可以用 need_password 或 user_is_authenticated 这样的名字来代替；

像 is 、has 、can或should这样的词，就可以把布尔值变得更明确。

审美

代码的审美，确切地说，有三条原则：

1. 使用一致的布局，让读者很快就习惯这种风格。

2. 让相似的代码看上去相似。

3. 把相关的代码行分组，形成代码块。

该写怎样的注释

1. 从代码本身快速推断出事实的不需要注释

2. 不要为了注释而注释

3. 不要给不好的名字加注释（不如改名字）

4. 加入“导演评论”，你可以在代码中加入注释来记录你对代码有价值的见解。

5. 为代码中的瑕疵写注释

6. 给常量加注释（有些常量不需要注释，因为它们的名字已经很清楚，但很多常量可以通过加注释得以改进）

7. 站在读者的角度，“全局观”注释

写出言简意赅的注释

1. 让注释保持紧凑

2. 避免使用不明确的代词（如it,this等）

3. 润色粗糙的句子

4. 精确地描述函数的行为

比如用输入/输出例子来说明特别的情况

下面是一个用来移除部分字符串的通用函数：

5. 声明代码的意图

对于“具名函数参数”的注释，就是像 C# Python 这类语言的命名函数参数，让每个参数的意义更加明确。

比如：

6. 采用信息含量高的词

l 避免使用代词

l 尽量精确描述函数的行为

l 精心挑选输入/输出的例子

l 声明代码的高层次意图，而非明显的细节

l 用嵌入注释解释难以理解的函数参数

l 用含义丰富的词语

简化循环和逻辑

1. 把控制流变得易读

l 条件语句中参数的顺序

比较左侧： “被询问”的表达式，它的值倾向于不断变化

比较右侧： 用来做比较的表达式，它的值更倾向于常量

l if/else 语句块的顺序

首先处理正逻辑而不是负逻辑

再处理简单的情况

最后处理有趣的或者是可疑的情况

l ?: 表达式, 只有在简单的情况下使用

l 避免 do/while 循环

l 从函数中提前返回

l 最小化嵌套

l 减少循环内嵌套

2. 拆分超长表达式

l 用做解释的变量

l 总结变量(用一个短很多的名字来代替一大块代码，这就是总结变量)

l 拆分巨大的语句

比如：

显而易见，这段代码逻辑很清晰，但是看着太复杂，下面改掉：

这样做有很多好处：

- 避免输入的错误。

- 缩短了行的宽度，更容易快速阅读。

- 如果类名字改变了，只需要改变一个地方就行了。

3. 变量与可读性

l 减少变量，即那些妨碍的变量。通过离开处理结果来消除“中间结果”的变量。

l 减少每个变量的作用域，越小越好。

l 只写一次的变量更好，那些只设置一次值的变量（或者 const 、final 、常量）使得代码更容易理解。

4. 抽取不相关的子问题

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

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

- 对于每一行代码，问下：它是为了目标而写的么？

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

l 纯工具代码（封装共用的函数）

l 其他多用途代码（比如页面上数据逻辑代码）

l 创建大量通用代码（组件）

- 通用代码很好，因为“完全地从项目的其他部分中解耦出来”。

l 项目专有的功能（私有组件）

l 简化已有接口，按需重塑接口

5. 一次只做一件事

应该把代码组织得一次只做一件事情。如何给代码整理碎片，下图演示了这个过程：

6. 把想法变成代码

如果有好的想法，则可以实现为代码，但需要注意以下几点：

l 清楚地描述逻辑

l 可了解相关函数库，以便减少代码量

l 把这个方法应用于更大的问题

l 用自然语言描述解决方案

l 递归地使用这种方法

7. 少写代码

“最好读的代码就是没有代码”，在收到一个需求的时候，要质疑和拆分你的需求，用小的代码库，去替代大的代码库；删除没有用的代码，简化实现过程；熟悉你周边的库，了解最优库；对于一些库的重用，可以极大的节省时间。

总结

以上就是关于可读性代码的建议和实现方式，好的代码不仅阅读轻松，维护起来也是事半功倍。养成好的书写处理习惯，会为我们的工作和学习带来极大的便利。