专栏首页java思维导图自下向上的编写容易阅读的代码(上)

自下向上的编写容易阅读的代码(上)

我在 关于极简编程的思考 中曾提到要编写可阅读的代码。因为代码是编写一次,阅读多次。 阅读者包括代码编写者,以及后来的维护人员。能让阅读代码更轻松,有利于增强项目或者产品的可维护性。

本博客分为上下俩部分,第一部分讲解在代码层次 编写可阅读的代码, 第二部分讲解方法,类,以及一些设计上的考虑 让代码更适合阅读。这些都是我在实际工作的一些体会以及代码审查过程中跟同事一起得出的一些经验。没有太高深的理论,适合所有人借鉴交流。

代码层次(上)

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<Order> 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的含义

总结

代码是一次写入,多次阅读,从代码层次去看待如何编写容易阅读代码,可能还能列出更多的规则,我个人觉得这些规则并不重要,重要的是能时刻想到后来人会如何阅读你的代码才是最重要的,如果他阅读你的代码,毫无障碍的达到一目十行,觉得你写的代码没什么高深,那就是好代码。

博文参考了 王垠的《编程的智慧》

  • 作者:闲大赋 链接:https://my.oschina.net/xiandafu/blog/1509679

本文分享自微信公众号 - java思维导图(java-mindmap),作者:闲大赋

原文出处及转载信息见文内详细说明,如有侵权,请联系 yunjia_community@tencent.com 删除。

原始发表时间:2018-01-18

本文参与腾讯云自媒体分享计划,欢迎正在阅读的你也加入,一起分享。

我来说两句

0 条评论
登录 后参与评论

相关文章

  • 编程中,有哪些好的习惯一开始就值得坚持?

    在项目的开始阶段,不要上手直接写代码,一定要先确定代码的分层和架构。该分层和架构在一定程度上决定了未来整个项目的代码风格和维护性,对于项目的长期维护,代码架构的...

    java思维导图
  • 程序员,请优先提高代码的可读性

    现在,当有人提及“优化”一词时,他们通常是指“优化执行时间”,除非他们明确表明要优化GPU的内存消耗,网络流量等等。

    java思维导图
  • 如何写出让同事无法维护的代码?

    总之,我们的口号是—— Write Everywhere, Read Nowhere

    java思维导图
  • 程序员提高编程能力万无一失的办法

    那就是去读别人写的代码。读那些你常用的库、编程框架的源代码,读那些你景仰的大牛的源代码,读代码里的测试(测试本身就是一种有效的文档);读代码、改代码、运行代码。...

    企鹅号小编
  • 三维空间内的向量的运算

    WolframChina
  • 顶尖程序员的五种思维模式,你具备吗?

    转自:程序人生(coder_life) 《THe Effective Engineer》的作者Edmond Lau采访了很多硅谷顶级科技公司的顶尖软件工程师。...

    顶级程序员
  • 编程中有哪些好习惯一开始就值得坚持?

    ITWorld 曾经发起了一个“程序员最头疼的事情”投票,结果非常有趣,近半数的程序员认为命名是最头疼的事情。

    用户4645519
  • 谁在代码里下的毒

    只要在公司上班,一个人负责一个项目的开发和维护这种情况很少会出现, 一般是由多个人合作开发一个项目, 在整个项目的生命周期内,不同的时间段, 同一份代码会由不同...

    用户1667431
  • 为什么开源可以提高程序员的编程技能?

    我已经写了很多年的软件。最近我意识到,我越涉及(致力于,结合于等)开源技术,我写出来的代码就更好。这不由地让我疑惑起来:难道里面有什么相关性或因果关系吗? ? ...

    用户1667431
  • 所有程序员都应该遵守的11条规则

    我是一个倾向于生活在规则下的人。 现在,这些规则大部分是我本人为自己设立的-但它们依然是规则。 我发现为自己创建规则可以让我过得更好,因为这样做可以提前决定一些...

    用户1667431

扫码关注云+社区

领取腾讯云代金券