什么叫可读性代码?

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

编写可读性代码

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

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. 少写代码

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

总结

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