前言
随着公司业务扩展,业务复杂度不断提升,人员增加,团队的协同开发成本就越来越高。代码的复用性、可读性、可维护性、影响范围,越来越不可控,代码的复杂度成指数型上升,项目变得越来越难维护。
综上所述总结出如下几个问题:
- 查看别人代码的机会越来越多,成指数型上升。
- 编码(风格不统一),不规范的代码,看起来往往都是逻辑复杂,命名不清晰,影响阅读速度。
- 代码没有(API文档、注释),不了解内部逻辑时,出现使用传参错误的情况,只能靠猜。
- 修改代码没有(测试用例),修改完成后无法验证代码的可用性,测试成本高,复现场景复杂。
- 对于项目结构(数据流图)、需求不清晰(产品功能地图),不能明确自己功能模块的职责边界。
- 哪些能力应该由框架提供?
- 哪些能力应该由插件提供?
- 哪些能力有复用性?
- 哪些能力没有复用性?
- 哪些组件可以复用?
- 组件的增加没有(统一组件/工具库目录),当两个开发人员,需要同一个组件承载数据时,因信息不透明,对同一个组件分别开发了两遍。
- 项目(工程结构复杂,分类不清晰),项目整体结构阅读起来也非常困难。
1. 编码风格
参考规范:Airbnb JavaScript Style Guide
校验工具:JSCS
1.1 在WebStorm中的配置JSCS校验
- 1.1.1 使用npm安装JSCS:
1 2 3 4 5 6 |
#当前项目安装 npm i --save-dev jscs #或者 全局安装 npm i -g jscs |
- 1.1.2 在项目的根目录创建配置文件:
.jscsrc
或.jscsrc.json
1 2 3 4 5 6 7 8 |
{ "preset": "airbnb", "maxErrors": 100, "requireSemicolons": false, "disallowTrailingWhitespace": false, "disallowEmptyBlocks": false } |
- 1.1.3 修改WebStorm 代码校验工具的 [配置文件]
1 2 |
Preferences-> Languages & Freameworks-> Code Quality Tools-> JSCS |
1.2 在WebStorm格式化工具配置Airbnb格式
- 1.2.1 打开配置界面
1 2 3 4 |
#打开配置界面 Preferences-> Editor-> Code Style Scheme-> Import Scheme-> Intellij IDEA code style XML |
- 1.2.2 导入airbnb-lk配置文件
1.3 配置完成
WebStorm可以提示代码风格错误,使用格式化可以修复部分简易代码风格错误。
1.4 项目分段改造
- 1.4.1 第一阶段 自行修改
- 针对新增页面、模块,要求按照Airbnb校验规则编码,不强制要求
- 1.4.2 第二阶段 强制修改
- 将Airbnb的规则加入Webpack loader中,强制在编译时校验,如果校验不通过,将编译失败无法进行其他业务代码的开发。
2. API文档注释
文档生成工具:Documentation
2.1 优先处理
- 优先 复杂业务逻辑 处理
- 优先 复用性较高 的业务模块处理
- 优先对 数据流 处理的函数
- 优先组件对 外部 提供的API(Props Function)
- 优先 使用方式复杂 的组件
2.2 代码注释TAG
- 常用注释
1 2 3 4 5 6 7 8 9 10 11 12 13 |
- @desc 方法描述(可省略@desc) - @ignore 表示忽略掉当前[class or function] - @public -@protected -@private 表示访问的权限 - @deprecated 表示弃用,可说明用xxx函数代替 - @experimental 表示实验函数,不稳定,可能包含破坏性修改 - {@link [class or function]} 可跳转到【文档库】的其他文档连接 - @see https://reactjs.org/ 可跳转到【外部文档】连接 - @since 1.0.0 从某个版本开始使用 - @version 1.2.3 某个版本编写 |
- 类注释
1 2 3 4 |
- @extend {class} 表示继承自哪个类(es6可省略) - @implements {Interface} 表示这个类是实现的某个接口类 - @interface 表示这个类只提供接口 |
- 方法/函数注释
1 2 3 4 5 6 7 8 9 |
- @param {参数类型} 参数说明 - @return {返回值类型} 返回值说明 - @abstract 表示这个方法必须被子类重写 - @override 表示这个方法重写父类的方法 - @emits {eventName} 表示这个函数发送的消息 - @listens {eventName} 表示这个函数监听的消息 - @throws {errorName} 表示这个函数会抛出中断错误 |
- 属性变量注释
1 2 3 |
- @type {Object} 表示变量/属性的类型(可作用于this/get/set) - @property {number} p.age 当type时Object对象时,可表示Object属性类型 |
- @type 类型说明
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
- @param {number} 简单类型 - @param {number|string} 多种类型 - @param {number[]} 数组类型 - @param {?number} 可空参数 - @param {!number} 不可空参数 - @param {?(number|string)} 多类型可空参数 - @param {number} [param] 选填参数 - @param {number} param=0 默认值是0 - @param {number} [param=0] 选填且默认值是0 - @param {Object} param 对象类型 - @param {number} param.count 对象类型的属性 - @param {string} param.type 对象类型的属性 - @param {{count: number, type: string}} 对象类型另一种写法 - @param {{count: ?number, type: ?string}} 对象类型可空类型写法 # 函数类型,函数可接收的参数类型,及返回值 - @param {function(foo: number, bar: string): boolean} |
3. 测试用例
校验工具:Jest
3.1 在WebStrom中配置Jest工具
- 3.1.1 使用npm安装Jest:
1 2 3 4 5 6 |
#当前项目安装 npm i --save-dev jest #或者 全局安装 npm i -g jest |
- 3.1.2 修改WebStrom 测试工具配置文件
1 2 3 |
#打开配置界面 Run-> Edit Configurations-> Add New Configuration-> Jest |
- 3.1.3 配置Jest支持ES6语法
-
使用npm安装babel
1 2 |
npm i --save-dev babel-cli babel-jest babel-preset-stage-0 |
- 创建.babelrc 配置文件(Jest默认加载
root/.babelrc
文件)
1 2 3 4 5 6 7 |
{ "presets": [ "es2015", "stage-0" ] } |
3.2 用例编写规范
-
3.2.1 需要用例覆盖的代码
Pure Function
- 算法库
- 组件库
- 业务逻辑代码
- 数据流处理
- 中间件处理
- 3.2.2 用例要求
- 独立仓库维护的组件,要求必须有测试用例、文档
- 每次修改代码时,要求测试用例验证通过
- 新增逻辑,要对应增加新的测试用例
3.3 项目改造
- 纯函数:所有的函数应针对API开发,编写纯函数,保证相同的参数,有相同的返回值。
- 组件仓库独立维护:项目中有大量的组件,可以抽象出共性组件,要创建独立仓库维护。
- 项目仓库独立维护:业务逻辑代码,要抽离于界面,编写纯函数处理。
- Git Submodule:增加【Git Submodule】管理子模块