【经验】不写注释 提升代码易读性的秘诀

大家好,欢迎来到停止重构的频道。

本期我们讨论一个比较开放的问题,如何写出规整易读的代码。

这听起来是一个小问题,但是实际上,所谓的屎山代码说白了就是杂乱无章的代码,理解的时间要比修改的时间多很多。

这些不可估量的理解成本,慢慢积累起来就是无限延期和无穷加班。

我们详细讨论下面几个问题:

1、没有注释的代码一定是屎山吗?

2、提升代码可读性的秘诀?

3、我们认为的代码更优形态

没有注释的代码一定是屎山吗?

首先讨论一个问题,没有注释的代码一定是屎山代码吗?

我在上学的时候是认为,注释肯定是能提升易读性的,不写注释的话总感觉过两天就看不懂了。

​而且写注释的过程也能进一步检查程序的逻辑,提前发现一些BUG。

但是参加工作后,却慢慢少写注释了

这当然有项目进度、工作压力等因素,项目主管总是催着快点完成任务。​那谁又愿意在加班后还继续加班写注释呢?

当然,这只是表面的因素。

更重要的是,在多人参与、长时间迭代升级的软件项目下,注释对代码理解的帮助其实没那么大

图中示例看起来还算好理解是因为代码行数少,如果这是一个两三百行且包含四五层嵌套if/else的话,那理解起来肯定是晕头转向的。

而且实际工作并不是看懂一个代码片段就可以了。

你往往需要理解十几个函数,才能判断BUG位置。修改了BUG也可能对其他功能造成影响,BUG越改越多。

何况你看到的注释还可能是个陷阱

注释可能是错误的,可能来自于当时开发人员对某个API的错误理解。

注释也可能是很旧的,是最开始的开发人员写的,但是之后修改的人都没有更新。

当然,这些都可以简单地说一句,个别开发人员太不负责任了,或者团队规范没做好活该。

但是主导了这么多项目后,我深有体会。

注释的维护本身就是一件非常奢侈的事情,很难要求每个开发人员都自愿花时间去写注释。

而且什么是必要的、清晰的、完整的注释也很难给出标准,难以给出标准的事情就,没有执行性可言

所以我们认为,屎山代码跟注释没多大关系。代码结构混乱、难以理解的代码才是屎山。

提升代码可读性的秘诀

​那如何提升代码可读性呢?

首先是工程结构要非常清晰,平衡好软件结构、开发效率、维护扩展成本的关系

关于工程结构规整化的问题,已经在往期前端规整化、后端规整化里提到过了,这里不作展开。

这里着重讨论单个函数、代码片段如何写,才能提升可读性。

首先需要在变量名、函数名、类名等定义时写明它们的作用,而不是用一些随便的、奇怪的拼音缩写。

代码即注释,这样就能很大程度提升代码的可读性。

另外,我们认为易读的代码片段应该是单层流程化的

也就是避免多层嵌套的if/else,可以通过提前返回、抽离函数等方式实现。

单层流程化的代码可以快速理解逻辑,每一个步骤只有通过和不通过。如果在每个流程前添加一下简单注释,就更清晰了​。

当然,完全的单层流程化代码可能会造成过多的碎片函数,所以单层的限定不需要太过苛刻,只需要尽量降低代码嵌套层数就可以了。

我们认为的代码更优形态

以上的方法只能提升代码的易读性,顶多从3天的理解时间下降到1天。

但开发人员不一定能完全遵守,而且根据破窗效应,只要有一个开发人员不遵守,慢慢地整个项目代码都会变得乱糟的。

那是否有什么方法?

可以让代码保持易读规整,开发、维护、扩展的效率大幅提高的同时,人员流动也不会造成影响呢?

这是我做架构师这几年一直在探索的问题。

比起各种花里胡哨的工具、框架,我更看重开发过程、项目质量。这些年也摸索试验出了一套顶层架构的设计方法论

首先代码应该分离为模块代码、业务代码两层。​模块代码是通用的功能代码,业务代码是对模块进行使用顺序编排以实现具体业务功能。

模块代码实现的是通用功能,需要写代码实现功能

以后端举例模块可以是检查必要参数、权限校验、大文件分片上传等模块。

前端的话模块可以是通用的播放器、聊天框、后端请求模块等。

模块要求完全独立,且可以单独运行调试。

另外,模块要求采用统一的使用方式,方便业务代码进行流程编排。

由于模块的这些特性,允许模块无条件复用在别的项目。

也可以不断积累扩展模块池规模,项目成本将越来越低。

另外,即使某个模块是临时快速开发的,也可以不需要太多顾虑地进行单独修改重构后替换。

业务代码主要是对模块使用顺序进行编排,以实现具体功能。

由于模块约束了统一的使用方式,所以业务代码可以不需要写代码

开发人员可以用Json配置文件等方式代替写代码,最后在程序运行前通过代码生成器生成真正的业务代码即可。

最终生成的业务代码其实就是极度规整化的单层流程化代码。

以后端举例,业务编排是对一个API处理流程的编排,如第一步检查必要参数、第二步检查权限、第三步插入数据。

前端的话,业务编排是对一个事件响应流程的编排,如提交表单按钮点击后,第一步调用表格模块获取资料,第二步调用后端通信模块请求后端,第三步调用提示模块显示结果,第四步调用导航模块跳转页面。

按以上方式分离代码后,可以让团队分工合作更加紧密顺畅。

业务代码由于不需要写代码调试,可以交由一些经验不足的开发人员完成。

模块代码开发,虽然要求有一定开发经验才能胜任,但是可以复用。

这样分工可以从根本上缓解开发工作量化的问题,效果就是成本预算更精准,更低计划预测也将更准确。

我们之前发布的前端框架Trick、后端框架Once、云计算框架Hive。

只有Once实现了以上所有的设想。而Trick、Hive由于数据流转、多线程同步等问题,当时是还没有实现业务代码的无代码编排化的。

但即使是这样,一个后端人员也足够支撑4-5个前端人员了。

而2023年我们解决了这些问题,Trick2、Once2、Hive2实现了以上的所有设想

它们将在今年内整理完发布,这也会成为后续低代码的内核,敢兴趣的小伙伴可以关注一下。

总结

当然,以上只是我们的看法、想法、做法。

如果有什么建议、意见,或者你探索出了更好的方式,欢迎在评论区一起讨论。​

  • 28
    点赞
  • 26
    收藏
    觉得还不错? 一键收藏
  • 0
    评论
评论
添加红包

请填写红包祝福语或标题

红包个数最小为10个

红包金额最低5元

当前余额3.43前往充值 >
需支付:10.00
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包
实付
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明:

1.余额是钱包充值的虚拟货币,按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载,可以购买VIP、付费专栏及课程。

余额充值