@ozo/react-rock

[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. 。。。