前言
随着公司业务扩展，业务复杂度不断提升，人员增加，团队的协同开发成本就越来越高。代码的复用性、可读性、可维护性、影响范围，越来越不可控，代码的复杂度成指数型上升，项目变得越来越难维护。
综上所述总结出如下几个问题：
- 查看别人代码的机会越来越多，成指数型上升。
- 编码（风格不统一），不规范的代码，看起来往往都是逻辑复杂，命名不清晰，影响阅读速度。
- 代码没有（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】管理子模块