HXDM前端开发规范安排上

说明

• 前端开发规范可能对于很多人都并不陌生，尤其是团队人数很多的基本都有属于自己的开发规范。有一个好的规范约束有哪些优势呢？
  1. 增强代码的可读性、可维护性；
  2. 避免出现低级的代码错误；
  3. 提高代码编写速度及质量；
  4. 提高多人合作时开发效率等。
  
• 本文章主要是整理了一些我之前作为部门规范制定者以及在日常开发中对自己的一些规范，希望能够帮到 HXDM，可以根据自己的情况适当的调整，有自己好的规范希望留言交流，谢谢大家（百忙抽时间整理本篇文章，点个赞支持一下，年前冲击一下三级）。

文件目录规范

• 以 vue 项目为例

src                               源码目录
|-- api                              所有api接口
|-- assets                           静态资源，images, icons, styles等
|-- components                       公用组件
|-- config                           配置信息
|-- constants                        常量信息，项目所有Enum, 全局常量等
|-- directives                       自定义指令
|-- filters                          过滤器，全局工具
|-- datas                            模拟数据，临时存放
|-- lib                              外部引用的插件存放及修改文件
|-- mock                             模拟接口，临时存放
|-- plugins                          插件，全局使用
|-- router                           路由，统一管理
|-- store                            vuex, 统一管理
|-- themes                           自定义样式主题
|-- views                            视图目录
|   |-- role                             role模块名
|   |-- |-- role-list.vue                    role列表页面
|   |-- |-- role-add.vue                     role新建页面
|   |-- |-- role-update.vue                  role更新页面
|   |-- |-- index.less                      role模块样式
|   |-- |-- components                      role模块通用组件文件夹
|   |-- employee                         employee模块

1. assets 目录

• assets 为静态资源，里面存放 images、 styles、 icons 等静态资源

|assets
|-- icons
|-- images
|   |-- background-color.png
|   |-- upload-header.png
|-- styles

HTML 编写规范

1. 使用 HTML5 声明，默认 utf-8 编码，适配移动端等；
2. 使用语义化的标签，例如：header、nav、section、footer、img 等；
3. 避免标签嵌套过深、不能出现空标签；
4. 缩进根据团队多数成员习惯统一使用 2 个或 4 个 空格；
5. 使用双引号 "，而非单引号；

CSS 编写规范

1. 命名使用BEM：BlockElementModifier是块（block）、元素（element）、修饰符（modifier）；
2. id 不能和 class 存在同名；
3. 单个 class 的长度不能超过三级，即：study-math-subject；
4. 多个属性可以合并的情况需要合并，例如：font、padding、margin、background、border-radius等；
5. 为 0 的属性去掉单位、类似 0.5px 这种首位为 0 带有小数的去掉首位的 0，即为 .5px；
6. 每个选择器及属性独占一行；
7. 避免全局样式污染，每个模块应该有自己唯一的 class 名开始；
8. 对于 less、scss文件，避免嵌套过深、公用变量应写在单独的文件中全局引入。

JavaScript 编写规范

1. 对于字符串使用单引号，字符串拼接优先使用模版字符串 ``；
2. 对象类型使用字面值创建对象，即：const user = {}；
3. 检测数据类型使用Object.prototype.toString

Object.prototype.toString.call(data).slice(8, -1).toLowerCase();
// string、number、math、array...；

4. 数组循环使用语义化的方法，例如：forEach遍历、filter 过滤、every 都满足、some 存在满足等；
5. 对于统一变量有多个值满足避免使用 && 符号写一长串，将满足的值放入数组，使用数组的includes方法判断，例如：

  if(number === 1 && number ===2 && number === 3) 
  =>
  [1, 2, 3].includes(number)；

6. 判断使用严格相等（===）和严格不想等（!==）避免使用（==）和（!=）产生隐式转换出现预料之外的情况。
7. 合理使用三目运算，避免多层三目运算嵌套，可以使用其他数据结构替换，例如：if-else、switch、object、map、array等；
8. this 转化命名使用 _this、self 两者之一代替；
9. 多使用 ES6（ES6+）有的新特性代替之前的写法；
10. 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性，例如：

if (age > 10 && age < 18) { ... }；

变量规范

1. 避免使用 var 声明变量，使用 let、const 代替；
2. 变量使用小驼峰命名，即首个单词小写，后面的每个单词首字母大些，例如：userAgeLists；
3. 变量命名应根据变量的作用语义化，例如：userObject、studentList 等；
4. 变量名避免非语义化简写，例如：condition -> condi/con 等；
5. 多处使用的常量应在公共文件中进行单独声明；
6. 常量命名全部大写，单词间用下划线隔开；
7. 引用类型的数据在操作时，应该拷贝一份，避免操作原始数据；

函数规范

1. 同变量名一样使用小驼峰命名方式；
2. 函数名应为 动词 或者 动词+名词 的形式，即：getUserInfo、delete。

// 常用动词
add 添加
get 获取/set 设置
create 创建/show 显示
start 启动/stop 停止
open 打开/close 关闭
read 读取/write 写入
load 载入/save 保存/update 更新
destory/remove 删除
begin 开始/end 结束,
backup 备份/restore 恢复
import 导入/export 导出,
split 分割/merge 合并
inject 注入/extract 提取,
attach 附着/detach 脱离
bind 绑定/separate 分离
view 查看/browse 浏览
edit 编辑/modify 修改
select 选取/mark 标记
copy 复制/paste 粘贴
undo 撤销/redo 重做
insert 插入/delete 移除
clean 清理/clear 清除
index 索引/sort 排序
find 查找/search 搜索
increase 增加/decrease 减少
play 播放/pause 暂停
launch 启动/run 运行
compile 编译/execute 执行
debug 调试/trace 跟踪
observe 观察/listen 监听
build 构建/publish 发布
input 输入/output 输出
encode 编码/decode 解码
encrypt 加密/decrypt 解密
compress 压缩/decompress 解压缩
pack 打包/unpack 解包
parse 解析/emit 生成
connect 连接/disconnect 断开
send 发送/receive 接收
download 下载/upload 上传
refresh 刷新/synchronize 同步
update 更新/revert 复原
lock 锁定/unlock 解锁
check out 签出/check in 签入
submit 提交/commit 交付
push 推/pull 拉
expand 展开/collapse 折叠
start 开始/finish 完成
enter 进入/exit 退出
abort 放弃/quit 离开
obsolete 废弃/depreciate 废旧
collect 收集/aggregate 聚集

3. 每个函数只做一个功能且不超过 100 行；
4. 语义不明显的函数强制需要加上函数注释，具体注释在后面再细说；
5. 对于可能出现异常的地方需要加上异常捕获；
6. 对于大概率出现的情况应该写在前面并提前返回（return）；

注释规范

1. 单个文件需要标注创建者及修改者，vscode 中可以使用 koroFileHeader 插件自动生成；

  /*
 * @Descripttion: 多处（2+）使用的方法
 * @version: 
 * @Author: username
 * @Date: 2020-12-29 10:45:42
 * @LastEditors: username
 * @LastEditTime: 2021-01-15 09:42:07
 */

2. 有歧义的函数、入参超过 2 个及以上必须添加函数注释；

/**
 * @description: 获取列表最后的id
 * @param { Number } pageNo 分页页数
 * @param { List } data 列表数据
 * @param { String } idName id属性的名称
 * @return { null | String | Number }
 */

3. html、vue 模版、jsx 语法中，有逻辑较复杂的地方需要添加注释；

页面组件规范

• vue 项目规范以 Vue 官方规范 中的 A 规范为基础，在其上面进行项目开发，故所有代码均遵守该规范。
• react 项目规范 Airbnb React/JSX Style Guide
  1. 单个页面代码行数应不超过 300 行（css / scss / less 代码除外）；
  2. 命名应语义化，每个功能页面一个文件夹，例如：user 用户、setting 设置、home 首页 等；
  3. 2 处及以上使用的公共模块应编写为公共组件；
  4. 组件名应该始终是多个单词组成并为小驼峰命名，内部的 name 属性和组件名称保持一致；

  // vue
  // userSetting.vue
  export default {
    name: 'userSetting'
    // ...
  };
  react
  // UserSetting.vue
  export default class UserSetting extends React.Component{ ... }
  

  5. 标签属性超过 三个 应换行显示，并每个属性独占一行；
  6. 相似度较高的模块，应考虑提取公共组件，通过 props 区分；
  7. ...

git 规范

1. 新功能要单独拉取一个分支，分支以开发功能命名；
2. 基础分支：master 线上环境、pre 预发环境、test 测试环境、 dev 开发环境；
3. master 分支只有前端主管/负责人有合并权限；
4. 代码提交前需要检查代码是否合规，不合规不予提交、不予合并；
5. 有增加的文件添加时需要查看是否需要提交到仓库，不需要的在 .gitignore 文件中添加；
6. 不得提交 node_modules、dist 等环境或打包文件到仓库；
7. 每次提交需要注明提交的内容是什么；

  commit 的类别，只允许使用下面7个标识。
  feat：新功能（feature）
  fix：修补bug
  docs：文档（documentation）
  style： 格式（不影响代码运行的变动）
  refactor：重构（即不是新增功能，也不是修改bug的代码变动）
  test：增加测试
  chore：构建过程或辅助工具的变动

8. 合并有冲突时，应在找到对应修改的人一起在本地解决冲突后再提交到仓库；
9. 禁止使用 git add * 添加本地文件；
10. ...

VS code 插件搭配

1. GitLens — Git supercharged // 查看git提交历史
2. koroFileHeader // 文件作者标注、函数注释等
3. eslint/tslint // 配置js/ts规范自动提示
4. Beautify // 根据配置文件自动格式化
5. Prettier - Code formatter // 搭配 Beautify

写在最后

补充

• 有些规范整理的匆忙，有一些遗漏，后续收集后再做加强补充。

支持一下

• 年底冲击掘金三级，百忙抽时间整理本篇文章，希望 HXDM 们点赞?支持一下。
• 作者正在参加 2020年人气创作者榜单，有票的兄弟可以支持一下，再次感谢大家。点我直达