代码规范-对抗软件复杂度

·  阅读 2259
代码规范-对抗软件复杂度

1、为什么需要代码规范

任何系统性的项目都需要架构设计,而架构设计的核心命题是控制复杂度

但随着项目的不断迭代,复杂度就会不断上升,研发效率就会不断下降。

而代码规范正是对抗软件复杂度的有效手段,通过约定俗成的规则,降低复杂度,提升研发效能。

从团队角度来说,统一的代码规范有利于减少阅读成本和理解成本,并且能提高代码质量,长期来说,项目的稳定且可维护,也能更好更快速的支撑业务发展。

2、代码是怎么变坏的

2.1、重复的代码

同一个功能,在不同的业务域,大家用同一种技术甚至不同技术都去实现了一遍,撇开复用性不说,当我们要去修改底层的逻辑实现时,上层调用有一个漏改都是莫大的风险。

2.2、早期有效的决策不再有效

初期,我们有能力把一段代码写的简洁且逻辑清晰,但是当业务不断迭代,逻辑就变得越来越复杂,当其他同学来接手时,是改还是不改,改了出问题谁来背锅?这是一个灵魂的拷问,然后一边叹气一边新增自己的代码。。。

2.3、过早的优化

过早的优化是万恶之源,为什么这么说,百万和千万级别日活的架构肯定是不一样的,架构是需要演进的,如果一开始百万级别日活就想奔着千万级别的架构去,不仅脱离了实际的业务需求,还浪费大量的人力物力财力,反而得不偿失,从实际出发,适合自己的才是最重要的。

2.4、对合理性没有苛求

技术方案往往都不是单一的,当我们有「能跑就行」的想法时,就会选择最简单粗暴的方案,但是往往这种方案的复用性和扩展性都很差,当历史的浪潮不断向前推进,就会演变成技术负债,后人一边叹气一边又在屎山上拉了一泡。

2.5、过度设计

调用链路就像老奶奶的裹脚布一样,又臭又长,一层又一层,增加理解成本,降低开发效率。

2.6、没有设计

没有设计也相当可怕,一个函数动辄上千行,剪不断理还乱,然后后来者又是一边叹气一边。。。

2.7、排期紧

曾经看到这么一个问题,为什么大厂屎山也这么多,高赞的前两个回答是这么说的:

  1. 因为只允许有写一遍就成的时间
  2. 因为能用就行,需求都排不过来

进入一个死循环,屎山越堆越高。。

3、如何让代码变好

3.1、命名

大到项目名、模块名、包名、对外暴露的接口,小到类名、函数名、变量名、参数名,只要是做开发,我们就逃不过「起名字」这一关。命名的好坏,对于代码的可读性来说非常重要,甚至可以说是起决定性作用的。

3.1.1、命名多长最合适?

有两种情况,一种命名特别短,对于代码的编写者来说,自己对代码的逻辑很清楚,总感觉用什么样的命名都可以达意,实际上,对于不熟悉你代码的同事来讲,可能就不这么认为了。

另一种,命名很长,觉得命名一定要准确达意,哪怕长一点也没关系,但是,如果函数、变量的命名很长,那由它们组成的语句就会很长。在代码列长度有限制的情况下,就会经常出现一条语句被分割成两行的情况,这其实会影响代码可读性。

原则上,命名是以能准确达意为目标。多换位思考,以阅读者的视角去考量命名是否够直观。

3.1.2、命名要可读、可搜索

什么是命名可读,指的是不要用一些特别生僻、难发音的英文单词来命名,更不要随意造词。

虽然我们并不排斥一些独特的命名方式,但起码得让大部分人看一眼就能知道怎么读。而生僻、难发音的单词会严重影响交流沟通。

其次是可搜索,我们在IDE中编写代码的时候,经常会用「关键词联想」的方法来自动补全和搜索。比如,键入某个对象「.get」,希望IDE返回这个对象的所有get开头的方法。

3.1.3、行业规范

还有一些行业通用的规范:

  1. 接口前缀加「I」,表示一个Interface。比如IUserService,对应的实现类命名为UserService;
  2. 弹窗后缀加「Dialog」,表示一个Dialog。比如AppUpdateDialog;
  3. 工具类后缀加「Utils」,表示一个工具类。比如TrackUtils;
  4. 等等;

3.1.4、示例

bad:

fun getName(){}
复制代码

good:

fun getUserName(){}
复制代码

3.2、注释

命名很重要,注释跟命名同等重要。

3.2.1、注释应该写什么?

注释的目的就是让代码更容易看懂。只要符合这个要求的内容,你就可以将它写到注释里。

比如,阐述代码的逻辑,你为什么这么做,想要达到什么样的效果等等。

3.2.2、注释是不是越多越好?

注释太多和太少都有问题。

太多,有可能意味着代码写得不够可读,需要写很多注释来补充。除此之外,注释太多也会对代码本身的阅读起到干扰。而且,后期的维护成本也比较高,有时候代码改了,注释忘了同步修改,就会让代码阅读者更加迷惑。

当然,如果代码中一行注释都没有,那只能说明这个程序员很懒,我们要适当督促一下,让他注意添加一些必要的注释。

3.2.3、注释类别

image.png

3.2.4、示例

bad:

    /**
     * 取消
     */
    protected fun cancelJob(job: Job?) {
        if (job != null && job.isActive && !job.isCompleted && !job.isCancelled) {
            job.cancel()
        }
    }
复制代码

good:

    /**
     * 取消协程 会抛出CancellationException
     * @param job 协程job
     */
    protected fun cancelJob(job: Job?) {
        if (job != null && job.isActive && !job.isCompleted && !job.isCancelled) {
            job.cancel()
        }
    }
复制代码

3.3、代码风格

3.3.1、函数、类多大才合适?

函数的代码行数不要超过一屏幕的大小,比如50行。

3.3.2、一行代码多长最合适?

最好不要超过IDE的显示宽度。当然,也不能太小,否则会导致很多稍微长点的语句被折成两行,也会影响到代码的整洁,不利于阅读。

3.3.3、善用空行分割单元块

对于比较长的函数,为了让逻辑更加清晰,可以使用空行来分割各个代码块。

除此之外,在类的成员变量与函数之间、静态成员变量与普通成员变量之间、各函数之间、甚至各成员变量之间,我们都可以通过添加空行的方式,让这些不同模块的代码之间,界限更加明确。写代码就类似写文章,善于应用空行,可以让代码的整体结构看起来更加有清晰、有条理。

3.3.4、格式化

使用统一的格式化规则,比如空格、换行等,格式化规则不统一,容易引起不必要的变更,不利于代码评审和历史变更查询。

3.3.5、示例

bad:

AlertDialog.Builder(context).setView(0).setTitle(R.string.dialog_title).setMessage(R.string.dialog_message).setIcon(0) .create()
复制代码

good:

AlertDialog.Builder(context)
            .setView(0)
            .setTitle(R.string.dialog_title)
            .setMessage(R.string.dialog_message)
            .setIcon(0)
            .create()
复制代码

3.4、编码技巧

3.4.1、把代码分割成更小的单元块

大部分人阅读代码的习惯都是,先看整体再看细节。所以,我们要有模块化和抽象思维,善于将大块的复杂逻辑提炼成类或者函数,屏蔽掉细节,让阅读代码的人不至于迷失在细节中,这样能极大地提高代码的可读性。不过,只有代码逻辑比较复杂的时候,我们其实才建议提炼类或者函数。毕竟如果提炼出的函数只包含两三行代码,在阅读代码的时候,还得跳过去看一下,这样反倒增加了阅读成本。

3.4.2、避免函数参数过多

我个人觉得,函数包含3、4个参数的时候还是能接受的,大于等于5个的时候,我们就觉得参数有点过多了,会影响到代码的可读性,使用起来也不方便。

一般有2种处理方法:

  1. 考虑函数是否职责单一,是否能通过拆分成多个函数的方式来减少参数。
  2. 将函数的参数封装成对象。

3.4.3、函数设计要职责单一

我们在前面讲到单一职责原则的时候,针对的是类、模块这样的应用对象。实际上,对于函数的设计来说,更要满足单一职责原则。相对于类和模块,函数的粒度比较小,代码行数少,所以在应用单一职责原则的时候,没有像应用到类或者模块那样模棱两可,能多单一就多单一。

整洁的代码只做好一件事,干脆利落,直接了当,易于阅读,易于维护。

3.4.4、移除过深的嵌套层级

代码嵌套层级过深往往是因为if-else、switch-case、for循环过度嵌套导致的。我个人建议,嵌套最好不超过两层,超过两层之后就要思考一下是否可以减少嵌套。过深的嵌套本身理解起来就比较费劲,除此之外,嵌套过深很容易因为代码多次缩进,导致嵌套内部的语句超过一行的长度而折成两行,影响代码的整洁。

针对层级嵌套过深的代码可以使用多态简化逻辑,移除不必要的if或else,也可以使用策略模式,提前return退出嵌套等。

3.4.5、少即是多

无形装逼最为致命:

  1. 过度设计:有的同学为了炫技,各种设计模式咔咔往上整,反而增加复杂度;
  2. 隐式耦合:这种是想炫技但功力不够的,设计的不够优雅反而留下后遗症;

建筑师米斯.凡德洛曾说过,less is more,提倡简单,反对度装饰的设计理念。简单的东西往往带给人们的是更多的享受。

4、客户端的技术栈

上面介绍了一些通用的规范,然而时代在变化,技术在演进,客户端的技术更新也是日新月异,因此也需要针对不同的技术栈有系统性的规约及代码风格。

比如:

  1. Java的文件名遵循驼峰命名法,而在Flutter中文件名使用下划线隔开;
  2. Java和Kotlin、OC和Swift,不仅有类型推导上的区别,还有一些语法糖的特性;
  3. 等等;

下面是端上现有的一些技术栈:

语言规范文档
AndroidJavaJava开发手册(嵩山版)Google Java Style Guide
AndroidKotlinKotlin Coding conventions
iOSObjective-CCoding Guidelines for Cocoa
iOSSwiftSwift Style Guide
跨端FlutterEffective Dart
跨端动态化xxx(json -> TypeScript)Google TypeScript Style Guide
其他配置文件(xml、yml,json)Google XML Document Format Style Guide
其他脚本、插件(Python、Shell、Groovy)Shell Style GuidePython Style Guide

google开源规约:google.github.io/styleguide/

5、治理手段

5.1、检测工具

通过一些类似Lint之类的检测工具,在编写阶段通过警告,把不符合规范的代码扼杀在摇篮里。

Alibaba Java Coding Guidelines

5.2、代码评审

代码评审也称code review,俗称cr,cr的意义在于,作为局中人,尽管我们在编写代码的时候小心翼翼,但也可能会在无意间犯下一个小错误,而此时cr的人作为旁观者,可有一语点醒梦中人的效果,而且从实际问题出发产生思想的碰撞,相互学习,也有利于提升团队整体的编码水平。

5.3、扫码行动

我们端上正在做一些代码的治理,删除无用代码,下线老代码,比如原有的灰度校验在全量之后理应下线老的逻辑代码。

5.4、代码重构

我们也正在做模块化的重构治理,把以前设计不合理或者不满足现状诉求的地方做改进和优化。

6、一点思考

治理行动我们可以一年来一次,但这很明显不是最好的解决办法,代码是人写的,工具是辅助是底线,如何长治久安,还是要从根源上着手下功夫,这就需要我们团结一致,从思想上认可,从行动上落实,认真做好code review,始终对代码保持敬畏,对自己的代码负责,做一个有信仰有追求的程序员。

7、相关书籍

8、参考文档

本文正在参加「金石计划 . 瓜分6万现金大奖」

收藏成功!
已添加到「」, 点击更改