我在 关于极简编程的思考 中曾提到要编写可阅读的代码。因为代码是编写一次，阅读多次。 阅读者包括代码编写者，以及后来的维护人员。能让阅读代码更轻松，有利于增强项目或者产品的可维护性。
本博客分为上下俩部分，第一部分讲解在代码层次 编写可阅读的代码， 第二部分讲解方法，类，以及一些设计上的考虑 让代码更适合阅读。这些都是我在实际工作的一些体会以及代码审查过程中跟同事一起得出的一些经验。没有太高深的理论，适合所有人借鉴交流。
代码层次（上）
if 语句保持主流程畅通
if(xxx){
return false;
}
if(yyy){
return false;
}
if(zzz){
throw new Exception();
}
//主逻辑代码在下面
.......
return true；
使用if语句，对于不符合主逻辑的，要尽早返回，这样可以减轻代码阅读者的负担，下次再看，直接就可以从主逻辑开始。直接跳过不关心的代码块（这样代码块必然返回都是fasle) 如下是一个不好的例子
if(xxx){
return false;
}
if(yyy){
return true;
}
//主逻辑代码在下面
在主逻辑前面分别返回了true 或者 false，阅读者会造成混乱，因为说明这个方法任何一处都有可能返回不同的情况,更糟糕的是
if(!xxx){
return true
}else{
if(yyy){
return false;
}else{
//主逻辑代码在下面
.......
return true；
}
}
显然这段代码会造成较大的阅读负担
尽可能多的去掉代码行的注释
/*
int c = getBalance(userId);
if(isGreat(date){
}
*/
int c = getBalance(userIddate);
显然，有多行是无用的注释，如果当初为了调试保留在这里，那么调试成功后要尽快删除，不要给后来人留下疑惑。
代码注释会随时过时，但IDE并没有像代码那样能充分管理注释，不需要的注释应该立即删除，如下注释刚开始看起来不错
public class User{
// 0 表示性别为女，1表示为男
int gender = 0;
}
项目中，状态值会随着项目发展而不断增加，上面的注释会误导阅读者以为性别只有俩个状态，正确的做法是
public class User{
int gender = Gender.MALE.value();
}
这样，阅读者可以通过枚举类找到性别对应所有的状态，比如 Gender.Male,Gender.FEMALE,Gender.UNKNOWN
使用一些中间变量来增强代码可读性
int total = a*b+c/rate+d*e;
上面的代码一气呵成，且只用了一行，但没有下面的代码更容易阅读
int yearTotal = a*b;
int lastYearTotal = c/rate;
int todayTotal = d*e;
int total = yearTotal+lastYearTotal+todayTotal;
看似其他人一行代码完成似乎更牛，你用了多行代码才完成了一个功能，但你的代码显然更容易被后来人阅读。我一直觉得写代码就跟写小说一样，要看得懂才是真正的小说，如果从任何地方切入都能看懂，那就是本好小说。
甚至可以将一部分代码封装到一个方法里，通过方法名和参数来提高可阅读性。后来者虽然第一阅读到这样的代码还需要进入方法体了解用法，但下次再次阅读，或者再次修改，就可以跳过他已经熟悉的方法，比如如下解析excel的文件，需要读出多个片段数据
public void parse(Sheet sheet){
User user = readUserInfo(sheet);
List orders = readUserOrderInfo(sheet);
UserCredit credit = readUserCreditInfo(sheet);
}
如上parse方法将分成三个方法完成，这对于性能和代码行数，可能略有影响（其实根本算不上影响），但增强了代码的可阅读性，如果后来人重构了用户积分部分，可以直接修改readUserCreditInfo方法，而不需要从上百行代码里找到自己应该修改的地方。
提倡使用一些短小方法来划分代码
......省略50行代码
int year =c.get(Calendar.YEAR);
int month = c.get(Calendar.MONTH)+1;
int month_date= c.get(Calendar.DATE);
String message ="今天"+year+"年"+month+"月"+month_date+"日，您在【业务系统】中有【"+paymentTotal+"】客户需要还款、有【"+settleTotal+"】客户需要结清、【"+verdueTotal+"】客户已经逾期，请尽快处理。";
.......省略50行代码
这段代码如果单独看尚可，如果这是在成百行代码的一部分，建议放到一个小方法里，比如，重构为
......
String str = getPayMessage（paymentTotal，settlleTotal,verdueTotal）
.......
protected String getPayMessage(BigDecimal paymentTooal,BigDecimalBigDecimal settlleTotal,verdueTotal){
int year =c.get(Calendar.YEAR);
int month = c.get(Calendar.MONTH)+1;
int month_date= c.get(Calendar.DATE);
String message ="今天"+year+"年"+month+"月"+month_date+"日，您在【业务系统】中有【"+paymentTotal+"】客户需要还款、有【"+settleTotal+"】客户需要结清、【"+verdueTotal+"】客户已经逾期，请尽快处理。";
}
重构后，代码阅读者每次看到这里，都会放心的跳过这部分代码。因为从方法名已经了解其作用，能很快的扫过这片代码区域
不要使用数组
程序里的数组只适合代码编写者看，阅读者无法判断数组代表的业务含义，比如
Object[] rets = call();
boolean success = (Boolean)rets[0];
String msg = (String)rets[1];
较好的方法是定义一个对象代替数组
CallResult rets = call();
boolean success = rets.isSuccess();
String msg = rets.getMessage();
也许你觉得调用后立刻转化成有意义的参数名会不影响阅读，这确实是一种补救办法，但不及CallResult好。代码编写者应该能时刻想到给阅读者减轻负担。
类似的列子还有JPA的查询，对于不能映射为实体的，总是返回一个数组，比如
Object[] array = jpa.query("select * from xxx ,yyy .....")；
Integer id = (Integer)array[0];
String name = (String)array[1];
.....
String tradeId = (String)array[22];
返回这样一个数组，如果sql要改写，那么代码对array的的处理也肯定要修改。看代码的人也不得不阅读这些无聊的代码。
相对于MyBatis和我写的BeetlSql，这一点JPA就不行了-提供了一个返回数组的查询接口。
我发现我每次在博客提到我写的开源，就有人说我想宣传自己的开源。我想强调一下，我只是践行知行合一，我不会轻易评判一个我不熟悉领域技术，除非我真的实践过。如果喷子对此不爽，你大可以忽略我“自我宣传部分”，仅看到我博客其他内容。
不一定要取有意义的变量名
java 里的for循环一般都是使用i变量，这说明了有些情况下，可以用一些简单的变量名字代替有意义的变量名字。前提是这些名字约定俗成，或者能在阅读代码的人眼里，这个变量就是几行之内就使用完毕，比如
boolean success = calc();
if(success){
return false;
}
success 变量可能不如paySuccess更好，但鉴于很快使用完毕，还是可以接受。相反，如果在sucess变量定义后面的100行，还用到了这个变量，那么“success” 就可能让人疑惑了，代码阅读者不得不再翻回去了解success的含义
总结
代码是一次写入，多次阅读，从代码层次去看待如何编写容易阅读代码，可能还能列出更多的规则，我个人觉得这些规则并不重要，重要的是能时刻想到后来人会如何阅读你的代码才是最重要的，如果他阅读你的代码，毫无障碍的达到一目十行，觉得你写的代码没什么高深，那就是好代码。
博文参考了 王垠的《编程的智慧》
下篇