文档章节

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

闲大赋
 闲大赋
发布于 2017/08/14 13:45
字数 1959
阅读 3569
收藏 115
点赞 25
评论 37

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

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

代码层次(上)

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

总结

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

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

下篇

© 著作权归作者所有

共有 人打赏支持
闲大赋

闲大赋

粉丝 1098
博文 86
码字总数 81146
作品 10
西城
架构师
加载中

评论(37)

云淡V
云淡V
很多观点不谋而合,赞赞赞,666
我今年大三
我今年大三
大多数情况。。更偏向喜欢整合成一行代码。。比如 三目运算。。
每周精粹
每周精粹
这里有更多案例 : http://jblog.top/article/details/255840
我有药
我有药
大神是如何炼成的
正版小神龙
正版小神龙
不错,都很有道理
久永
久永
象牙塔学问,编写了几年代码?
建议大家参考下,别太当真。
很多是错的经验和没有经过充分实践的想象。
马丁的早晨
马丁的早晨

引用来自“闲大赋”的评论

引用来自“马丁的早晨”的评论

下篇什么时候出
有素材,不过得周末有空写一下,下周出下篇
:laughing:

好的,y( ˙ᴗ. )耶~
闲大赋
闲大赋

引用来自“马丁的早晨”的评论

下篇什么时候出
有素材,不过得周末有空写一下,下周出下篇
:laughing:
马丁的早晨
马丁的早晨
下篇什么时候出
cc90
cc90

引用来自“大弹簧”的评论

所见略同, 我代码里面都是这样写的,保持 if畅通, 分支结构在 if 里面,主结构在外面, 可读性、逻辑性、代码的组织结构,都会狠清晰

迭代和递归

迭代和递归 递归:是自顶向下逐步拓展需求,最后自下向顶运算。即由f(n)拓展到f(1),再由f(1)逐步算回f(n) 迭代:是直接自下向顶运算,由f(1)算到f(n)。 2. 迭代和递归 递归是在函数内调用本...

oneboi ⋅ 2016/10/17 ⋅ 0

iOS开发捷径学习(三)

Storyboard的segue Storyboard中的segue功能强大,是页面跳转与交互的利器。现在就了解下吧。 初始化 segue的三个参数: identifier:唯一标识,用于标识自己 sourceViewController:来源控制...

智小融 ⋅ 01/02 ⋅ 0

每周「Paper + Code」清单:句子嵌入,文本表示,图像风格转换

在碎片化阅读充斥眼球的时代,越来越少的人会去关注每篇论文背后的探索和思考。 在这个栏目里,你会快速 get 每篇精选论文的亮点和痛点,时刻紧跟 AI 前沿成果。 点击本文底部的「阅读原文」...

c9yv2cf9i06k2a9e ⋅ 2017/12/21 ⋅ 0

Java 8 新语法习惯 (提倡使用有帮助的编码)

表达能力强是函数式编程的优势之一,但是这对于我们的代码意味着什么呢?在这部分内容中,我们将比较命令式和函数式代码的示例,判断这两种的表达能力和简洁性的能力。我们还能够了解到这些品...

晁东洋 ⋅ 01/08 ⋅ 0

代码质量对系统的影响

读了InfoQ中国的一篇新闻,题目为《代码永远是罪魁祸首吗》,有些想法不吐不快。代码质量一直是我较为关注的一个话题。我在许多场合提到过这一点,也就此写过博客来阐述我的观点。例如,在2...

wayfarer ⋅ 2010/12/20 ⋅ 0

合并排序(C语言实现)

递归算法是把一个问题分解成和自身相似的子问题,然后再调用自身把相应的子问题解决掉。这些算法用到了分治思想。其基本模式如下: 分解:把一个问题分解成与原问题相似的子问题 解决:递归的...

技术mix呢 ⋅ 2017/11/09 ⋅ 0

重构 阅读心得(转)

最近阅读Martin Flower的《重构》,对自己有许多启发,以前认为一些正确的观点现在看来也不那么正确了;同时发现对重构的理解只有在阅读了书之后更加彻底;在阅读《重构》之后我对其中几点有...

程序员小崔 ⋅ 2014/11/20 ⋅ 0

NetBeans的快捷键使用

完成代码:ctrl+ //任何地方按下此组合键,均会提示相应的参考字段; 错误提示:alt + enter //顾名思义,当系统报错时,按下此组合可以查看系统提示; 自动完成字符串: ctrl+L ctrl+k //后...

Junn ⋅ 2014/03/11 ⋅ 0

阅读优秀代码是提高开发人员修为的一种捷径

编者按:原文作者Alan Skorkin是一名软件开发人员,他在博客中分享对软件开发相关的心得,其中有很多优秀的文章,本文是其中的另一篇。Alan认为:阅读优秀代码是提高开发人员修为的一种捷径。...

jobBole ⋅ 2011/01/24 ⋅ 13

七天LLVM零基础入门(Linux版本)------第五天

作者:snsn1984 第一步:复习文档 Write an LLVM pass http://llvm.org/docs/WritingAnLLVMPass.html 第二步:阅读LLVM编程规范 http://llvm.org/docs/CodingStandards.html 编程规范是编程中......

snsn1984 ⋅ 2013/02/28 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

Spring Bean基础

1、Bean之间引用 <!--如果Bean配置在同一个XML文件中,使用local引用--><ref bean="someBean"/><!--如果Bean配置在不同的XML文件中,使用ref引用--><ref local="someBean"/> 其实两种......

霍淇滨 ⋅ 25分钟前 ⋅ 0

05、基于Consul+Upsync+Nginx实现动态负载均衡

1、Consul环境搭建 下载consul_0.7.5_linux_amd64.zip到/usr/local/src目录 cd /usr/local/srcwget https://releases.hashicorp.com/consul/0.7.5/consul_0.7.5_linux_amd64.zip 解压consu......

北岩 ⋅ 28分钟前 ⋅ 0

Webpack 4 api 了解与使用

webpack 最近升级到了 v4.5+版 01 官方不再支持 node4 以下版本 官方不再支持 node4 以下版本官方不再支持 node4 以下的版本,所以如果你的node版本太低,先开始升级node吧!话说node10 ...

NDweb ⋅ 37分钟前 ⋅ 0

使用nodeJs安装Vue-cli

Vue脚手架就是一个Vue框架开发环境 脚手架的意思是帮你快速开始一个vue的项目,也就是给你一套vue的结构,包含基础的依赖库,只需要 npm install就可以安装,让我们不需要为了编辑或者一些其...

木筏笔歆 ⋅ 今天 ⋅ 0

【微信小程序开发实战】0x00.开发前准备工作

写在开始 本人资深后端码农一枚,近期项目需求,接触到了微信小程序,将学习过程整理成文分享给小伙伴们,由于是边学边整理难免有表述不对的地方,望大家及时指正,感谢。 本人微信号: dream...

dreamans ⋅ 今天 ⋅ 0

linux redis的安装和php7下安装redis扩展

安装redis服务器 (1)下载安装包: $ wget http://download.redis.io/releases/redis-2.8.17.tar.gz (2)编译程序: $ tar xzf redis-2.8.17.tar.gz $ cd redis-2.8.17 $ make $ cd src &&......

concat ⋅ 今天 ⋅ 0

Guava EventBus源码解析

一、EventBus使用场景示例 Guava EventBus是事件发布/订阅框架,采用观察者模式,通过解耦发布者和订阅者简化事件(消息)的传递。这有点像简化版的MQ,除去了Broker,由EventBus托管了订阅&...

SaintTinyBoy ⋅ 今天 ⋅ 0

http怎么做自动跳转https

Apache 版本 如果需要整站跳转,则在网站的配置文件的<Directory>标签内,键入以下内容: RewriteEngine on RewriteCond %{SERVER_PORT} !^443$ RewriteRule ^(.*)?$ https://%{SERVER_NAME......

Helios51 ⋅ 今天 ⋅ 0

Python爬虫,抓取淘宝商品评论内容

作为一个资深吃货,网购各种零食是很频繁的,但是能否在浩瀚的商品库中找到合适的东西,就只能参考评论了!今天给大家分享用python做个抓取淘宝商品评论的小爬虫! 思路 我们就拿“德州扒鸡”...

python玩家 ⋅ 今天 ⋅ 0

MySQL 内核深度优化

MYSQL数据库适用场景广泛,相较于Oracle、DB2性价比更高,Web网站、日志系统、数据仓库等场景都有MYSQL用武之地,但是也存在对于事务性支持不太好(MySQL 5.5版本开始默认引擎才是InnoDB事务...

java高级架构牛人 ⋅ 今天 ⋅ 0

没有更多内容

加载失败,请刷新页面

加载更多

下一页

返回顶部
顶部