[TOC]

# 前端开发规范

为什么而“规范”？现在的项目都是团队协作。如果没有规范来进行约定和约束，会产生一系列的问题：

+ 团队编码风格不一致，增加代码阅读成本，加大团队协作和维护成本。

+ 没有良好的注释，开发人员切换时，增加转交项目时的培训成本，后期也很难继续维护。

  

通过建立一套适合团队的规范，可以降低团队的协作成本和维护成本，提高开发效率和质量，保证不会因为开发人员的变动而产生较大的影响。

> 这里的规范不涉及工作流程规范，每个团队的工作流程都不一样，主要跟公司业务相关的。

我们将从以下层级来进行规范：

* 框架级规范
* 项目级规范
* 代码级规范
* 其他约定



## 框架级规范

框架级规范主要针对框架、库、脚手架工具等指定的规范。

### 框架和 UI 库

针对不同的技术栈，应根据团队的特点和能力，确定今后团队的技术选型，不能随意更改选定好的框架和 UI 库。因为不同的框架、UI 库之间的风格难以统一，且可能存在兼容性；比如：

页面流： [jquery](https://github.com/jquery/jquery) + [bootstrap](https://github.com/twbs/bootstrap)

数据流： [react](https://github.com/facebook/react) + [ant-design](https://github.com/ant-design/ant-design)  /  [icedesign](https://alibaba.github.io/ice/component/breadcrumb)

可视化：react + antV-F2 / G2 （有对应的react库）



### 脚手架工具

脚手架工具使开发变得极为便利和高效，其中可以对代码风格、项目结构等进行统一规范。

- [eslint](https://github.com/eslint/eslint)：语法规则和代码风格检查，可以用来保证写出语法正确、风格统一的代码。
- [prettier](https://prettier.io/)：强大的代码风格检查和纠正，支持主流的编程语言。
- [stylelint](https://github.com/stylelint/stylelint)：CSS 风格审查，有助于开发者推行统一的样式规范，避免样式错误。



## 项目级规范

项目级规范主要包括项目结构规范，文件、目录命名规范，组件化规范等等，这些规范有些是构建工具要求的，有些是团队自己定的。

### 项目结构规范

良好的项目结构规范应基本需要满足以下几个需求：

- **便利性：**能够快速的定位文件位置，对编辑器友好
- **解耦性：**不同页面之间，不同组件之间是相互解耦的，不会更改一个组件或页面而影响到其他组件或页面
- **扩展性：**能够很方便的扩展组件和页面，而不会带来副作用
- **阅读性：**具有很好的阅读性，对组件、页面以及内部结构能够一目了然

在本脚手架中：

1. 项目级资源都在`src/assets`中，便于引用和集中管理。
2. 采用组件分级和私有组件机制，保证组件的单一性和可移植性。
3. 结构统一，新添加页面或组件时，直接复制原有的页面或组件，方便快捷。也便于自动化处理。
4. 组件划分容器组件和展示组件，明确两类组件的边界，引用解耦。
5. 。。。

### 文件/目录命名规范

- 项目非组件部分的目录和文件，采用小驼峰书写方式， 例：`myHome`
- 组件目录/文件，除入口index.js文件外，采用大驼峰书写方式， 例：`Placeholder,PageContainer`
- 完整英文命名的用复数形式，缩写用单数形式。例：`js, css, styles,images, img`

```js
components/Header
layouts/BlankLayout

components/Header/Header.jsx
components/Header/Header.scss
components/Header/Header.module.scss
components/Header/index.js
```

### 组件化规范

组件化规范不是指在代码、框架层面的组件化，而是在架构和规范层面的组件化。例如规范组件的统一样式/定义/引用/说明/示例等。在本脚手架中：

1. 采用scss统一管理通用样式变量，便于统一修改和UI规范。
2. 组件分级，组合开发时，可以快速定位到对应的组件。
3. 统一出口，强调从意识上加强组件的注册机制，并统一组件的引用方法。
4. 。。。



## 代码级规范

代码级规范针对具体的程序代码，包括代码风格和代码质量两个方面。

### 代码风格规范

- `html`: 主要有缩进，标签，加载顺序等等。所有 HTML 文件编写应当遵循 [HTML 编码规范](./HTML编码规范.md)。单页应用可以例外。更多参考：
  + [Code Guide](http://imweb.github.io/CodeGuide/)

- `css`：主要有缩进，换行，引号，注释等等。所有样式文件（css/scss）编写应当遵循 [CSS 编码规范](./CSS编码规范.md)。更多参考：
  + [Idiomatic-CSS 编码规范](https://github.com/necolas/idiomatic-css)

- `js`：主要有缩进，换行，变量名称，括号，文档注释等等。所有 js 文件编写应当遵循 [JavaScript 编码规范](./JS编码规范.md)。更多参考：
  + [Airbnb 代码规范](https://github.com/airbnb/javascript)
  + [Google 代码规范](https://google.github.io/styleguide/jsguide.html)
  + [Idiomatic 代码规范](https://github.com/rwaldron/idiomatic.js)
  + [Javascript 标准规范](https://github.com/standard/standard)

本脚手架中，通过引入`eslint` / `prettier` / `stylelint`三个插件来保证团队在代码风格和代码质量上的一致。可以通过根目录下的对应的配置文件（.eslintrc.js / .prettierrc / stylelint.config.js）进行配置。

此外，还可以通过配置`.editorconfig`，来统一编辑器的配置。



### 代码质量规范

代码质量规范是从代码的编写习惯和技巧、记录重点、注释等方面来进行统一。

#### 开发技巧

- 页面都放到pages目录，然后以模块分包。
- store的文件名称使用大写，实例化时使用驼峰命名法。
- 定义变量使用驼峰命名法。
- 定义配置型常量使用权大写和下划线分隔。
- 写代码的时候，请使用 ES6 即以上标准。
- 每个组件的index.js、类文件都要在文件头上上写中文注释，注释内容为文件的作用和注意事项等。
- 布局推荐使用flex布局，需注意flex与部分css3特性的适配问题。
- 多用 `const` ，少用 `let` ，不用`var`。
- 合理使用箭头函数。
- 渲染相关函数，使用render开头。
- 事件相关函数使用handle开头。
- 同一份数据，不要保存在两个不同的`store`里面。
- 每个`store`更新不同的数据，定义单独的`@action`。
- 数据更新，全部在`store`里面进行，不要在React的组件内进行。
- 在 `render()` 函数里不要去更新 `store`的数据,或者`setState`。




#### 记录重点

开发过程中，包括业务逻辑、更新日志、bug记录、踩坑日记与备注等也需要加强记录。

##### 业务逻辑

比较复杂的业务逻辑不太适合放在注释里面，需要单独写逻辑文档，以备后面查看。

有些逻辑并不是简单的用文字描述就能说的清楚的，还需要辅助流程图/思维导图以及表格等进行说明。

特别是存在前后端约定的环节，需要重点记录备案。

##### 更新日志

更新日志也是一个比较重要文档，能够方便查找更新状态、时间、开发人员等。

包括代码行的修改日志和更广级别的更新等。

##### bug记录及踩坑日记

日常开发中遇到的坑和bug都应该一一记录在册，附带对应的解决方案。

[bug记录](./doc/bug记录.md)

[踩坑日记](./doc/踩坑日记.md)

##### 备注

如果有额外的一些信息，需要用文档备注一下。

#### 注释（只讨论 `js`）

使用主流的JSDoc来规范注释，详情请参考[JSDoc注释规范](JSDoc注释规范.md)。



## 其他约定

1. 每个函数不建议超过20行

2. 每个 js 文件不应该超过 `400` 行，超过就应该分块

3. 每个 css 文件不应该超过 `200` 行，超过就应该分块

4. 。。。