编写可读代码的艺术（一）-- 表面层次的改进

编写可读代码的艺术（一）-- 表面层次的改进

代码应易于理解

1、代码应易于理解

关键思想：代码应该易于理解

1.1、代码的写法应当使别人理解他时间最小化

类、方法、变量应达到自注释，看到名称就可以知道含义

1.2、代码并不是越短越好

如果一行代码的可读性低于2行代码，那么应该写2行

2、把信息封装到名字里

关键思想：把信息封装进名字

eg：查询用户信息,query()， 改为listUserInfo();

2.1、 选择专业的词

// 获取用户信息
getUserInfo();

// 根据方法具体的内容将方法名调整为
fetchUserInfo();
// 或者
downloadUserInfo();

2.2、避免泛泛的名字

// before
boolean test = isUserExisted();
if (test){
	...
}

// after
boolean userExist = isUserExisted();
if (userExist) {
	...
}

2.3、用具体代替抽象

// 检测服务是否可以监听某个特定的TCP/IP端口
// before
void servertCanStart();

// after
void canListenOnPort();

2.4、使用前缀或者后缀表达更多的信息

void userName();

// 用后缀en标识用户英文名称
void userNameEn();

1.2.5、决定名字的长度

名字并非越长越好，例如UserBasicInfoFromChinaAndUsAndAmerican（）；名字避免过长，也避免单个单词，无法表达含义；

• 局部作用域里可以使用短的名字
• 作用域大的，如果没有合适的短名字，可以采用较长的名字
• 缩略词代替整个单词
  但是，仅限于大家共识中的缩略词。比如：desc代替description，doc代替document，str代替string
• 去掉没用的单词
  eg: convertToString，可以直接改为toString

2.6、利用名字的格式来表达含义

有目的的使用大小写、下划线等格式
eg:

// max_number 代表变量
max_number = 1000;

// 所有字母大写 代表常量
MAX_NUMBER = 1000;

3、不会误解的名字

本章关键思想：这个名字会给别人造成歧义吗

3.1、eg1：filter

User.filter(age < 12);
// 问题来了，User.filter()之后，获得的是age<12岁的，还是age>=12的，容易造成歧义

3.2、eg1：clip

clip(text, lengh);
// 问题来了，clip是剪切长度为lenth的内容，还是剪切后留下长度为length的内容

3.3、推荐使用min和max来表示包含的极限

int CAR_BIG_LIMIT = 100;
// 参数命名做调整,剪短，且易于理解
int MAX_ITEM_IN_CAR = 100;

3.4、推荐使用first、last来表示包含的范围

[first,last] 左开区间，右闭区间

3.5、推荐使用begin、end来表示范围

[begin,end) 左闭区间，右开区间

3.6、为布尔值命名时，用is、has作为前缀

避免使用反义词

4、注释

关键思想：尽量帮助读者了解和作者一样多

4.1、 不要写多余的无畏的注释

4.2、注释并不是越多越好，方法、代码最好自注释

4.2、为代码中的瑕疵写注释

TODO：待处理的事
FIXME：已知的无法运行的代码
HACK：对于一个问题，不得不采用的粗糙的解决方案
XXX：危险，这里有重要的问题

4.3、为常量写注释

4.4、为方法注释可能出现的陷阱

// 1分钟后，可能超市
void saveUser();

4.5、全局观注释

eg：为一个工具类添加注释：该类用于处理权限相关的基本问题

4.6、总结性注释

eg：为一个复杂的方法添加注释：迭代用户，根据用户的身份信息校验是否存在不合规行为

5、改写什么样的注释

关键信息：注释应该有相当高的信息/空间率

5.1、 it、this等代词可能指代多个事物时，应避免使用

5.2、尽量精确的描述函数的行为

5.3、在注释中用精心挑选的输入/输出例子进行说明

5.4、声明代码的高层次含义，而非细节

5.5、尽含义丰富的词来使注释简洁

[总结]编写可读代码的艺术