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

1、为什么需要代码规范

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

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

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

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

2、代码是怎么变坏的

2.1、重复的代码

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

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

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

2.3、过早的优化

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

2.4、对合理性没有苛求

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

2.5、过度设计

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

2.6、没有设计

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

2.7、排期紧

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

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

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

3、如何让代码变好

3.1、命名

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

3.1.1、命名多长最合适？

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

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

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

3.1.2、命名要可读、可搜索

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

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

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

3.1.3、行业规范

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

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

3.1.4、示例

bad：

代码语言：javascript复制

fun getName(){}

good：

代码语言：javascript复制

fun getUserName(){}

3.2、注释

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

3.2.1、注释应该写什么？

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

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

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

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

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

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

3.2.3、注释类别

3.2.4、示例

bad：

代码语言：javascript复制

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

good：

代码语言：javascript复制

    /**
     * 取消协程 会抛出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：

代码语言：javascript复制

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

good：

代码语言：javascript复制

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种处理方法：

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

3.4.3、函数设计要职责单一

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

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

3.4.4、移除过深的嵌套层级

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

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

3.4.5、少即是多

无形装逼最为致命：

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

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

4、客户端的技术栈

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

比如：

Java的文件名遵循驼峰命名法，而在Flutter中文件名使用下划线隔开；
Java和OC是强类型语言，Swift和Kotlin是弱类型语言，不仅有类型推导上的区别，还有一些语法糖的特性；
等等；

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

端	语言	规范文档
Android	Java	Java开发手册（嵩山版）Google Java Style Guide
Android	Kotlin	Kotlin Coding conventions
iOS	Objective-C	Coding Guidelines for Cocoa
iOS	Swift	Swift Style Guide
跨端	Flutter	Effective 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