说明
- 前不久写了一篇 从实际项目谈开发规范,你中招了吗? 谈及项目中的一些问题规范,这儿整理一些日常前端开发中都应该注意的地方。歧义之处,遵循自己即可,断不可较真。
- 前端开发规范可能对于很多人都并不陌生,尤其是团队人数较多的基本都有属于自己团队的一套开发规范。有一个好的规范约束有哪些优势呢?
1. 增强代码的可读性、可维护性;
2. 避免出现低级的代码错误;
3. 提高代码编写速度及质量;
4. 提高多人合作时开发效率等。 - 本文章主要是整理了一些我之前作为部门规范制定者以及在日常开发中对自己的一些规范,希望能够帮到各位掘友。也可以根据自己的情况适当的调整,有自己好的规范希望留言交流,谢谢大家(百忙抽时间整理本篇文章,点个赞支持一下,年前冲击一下三级)。
文件目录规范
- 以
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模块
assets
目录
assets
为静态资源,里面存放images
、styles
、icons
等静态资源
|assets
|-- icons
|-- images
| |-- background-color.png
| |-- upload-header.png
|-- styles
HTML
编写规范
- 使用
HTML5
声明,默认utf-8
编码,适配移动端等; - 使用语义化的标签,例如:
header
、nav
、section
、footer
、img
等; - 避免标签嵌套过深、不能出现空标签;
- 缩进根据团队多数成员习惯统一使用
2
个或4
个 空格; - 属性使用双引号
"
,而非单引号;
CSS
编写规范
- 命名使用
BEM
:BlockElementModifier
是块(block
)、元素(element
)、修饰符(modifier
); id
不能和class
存在同名;- 单个
class
的长度不能超过三级,即:study-math-subject
; - 多个属性可以合并的情况需要合并,例如:
font
、padding
、margin
、background
、border-radius
等; - 为
0
的属性去掉单位、类似0.5px
这种首位为0
带有小数的去掉首位的0
,即为.5px
; - 每个选择器及属性独占一行;
- 避免全局样式污染,每个模块应该有自己唯一的
class
名开始; - 对于
less
、scss
文件,避免嵌套过深、公用变量应写在单独的文件中全局引入。
JavaScript
编写规范
- 对于字符串使用单引号,字符串拼接优先使用模版字符串 ``;
- 对象类型使用字面值创建对象,即:
const user = {}
; - 检测数据类型使用
Object.prototype.toString
Object.prototype.toString.call(data).slice(8, -1).toLowerCase();
// string、number、math、array...;
- 数组循环使用语义化的方法,例如:
forEach
遍历、filter
过滤、every
都满足、some
存在满足等; - 对于统一变量有多个值满足避免使用
||
符号写一长串,将满足的值放入数组,使用数组的includes
方法判断,例如:
if(number === 1 || number ===2 || number === 3)
=>
[1, 2, 3].includes(number);
- 判断使用严格相等(
===
)和严格不想等(!==
)避免使用(==
)和(!=
)产生隐式转换出现预料之外的情况。 - 合理使用三目运算,避免多层三目运算嵌套,可以使用其他数据结构替换,例如:
if-else
、switch
、object
、map
、array
等; this
转化命名使用_this
、self
两者之一代替;- 多使用
ES6
(ES6+
)有的新特性代替之前的写法; - 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔开来以提升可读性,例如:
if (age > 10 && age < 18) { ... };
变量规范
- 避免使用
var
声明变量,使用let
、const
代替; - 变量使用小驼峰命名,即首个单词小写,后面的每个单词首字母大些,例如:
userAgeLists
; - 变量命名应根据变量的作用语义化,例如:
userObject
、studentList
等; - 变量名避免非语义化简写,例如:
condition
->condi
/con
等; - 多处使用的常量应在公共文件中进行单独声明;
- 常量命名全部大写,单词间用下划线隔开;
- 引用类型的数据在操作时,应该拷贝一份,避免操作原始数据;
函数规范
- 同变量名一样使用小驼峰命名方式;
- 函数名应为 动词 或者 动词+名词 的形式,即:
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 聚集
- 每个函数只做一个功能且不超过
100
行; - 语义不明显的函数强制需要加上函数注释,具体注释在后面再细说;
- 对于可能出现异常的地方需要加上异常捕获;
- 对于大概率出现的情况应该写在前面并提前返回(
return
);
注释规范
- 单个文件需要标注创建者及修改者,
vscode
中可以使用koroFileHeader
插件自动生成;
/*
* @Descripttion: 多处(2+)使用的方法
* @version:
* @Author: username
* @Date: 2020-12-29 10:45:42
* @LastEditors: username
* @LastEditTime: 2021-01-15 09:42:07
*/
- 有歧义的函数、入参超过
2
个及以上必须添加函数注释;
/**
* @description: 获取列表最后的id
* @param { Number } pageNo 分页页数
* @param { List } data 列表数据
* @param { String } idName id属性的名称
* @return { null | String | Number }
*/
html
、vue
模版、jsx
语法中,有逻辑较复杂的地方需要添加注释;
页面组件规范
vue
项目规范以 Vue 官方规范 中的A
规范为基础,在其上面进行项目开发,故所有代码均遵守该规范。react
项目规范 Airbnb React/JSX Style Guide- 单个页面代码行数应不超过
300
行(css
/scss
/less
代码除外); - 命名应语义化,每个功能页面一个文件夹,例如:
user
用户、setting
设置、home
首页 等; 2
处及以上使用的公共模块应编写为公共组件;- 组件名应该始终是多个单词组成并为小驼峰命名,内部的
name
属性和组件名称保持一致;
// vue // userSetting.vue export default { name: 'userSetting' // ... }; react // UserSetting.vue export default class UserSetting extends React.Component{ ... }
- 标签属性超过 三个 应换行显示,并每个属性独占一行;
- 相似度较高的模块,应考虑提取公共组件,通过
props
区分; - ...
- 单个页面代码行数应不超过
git
规范
- 新功能要单独拉取一个分支,分支以开发功能命名;
- 基础分支:
master
线上环境、pre
预发环境、test
测试环境、dev
开发环境; master
分支只有前端主管/负责人有合并权限;- 代码提交前需要检查代码是否合规,不合规不予提交、不予合并;
- 有增加的文件添加时需要查看是否需要提交到仓库,不需要的在
.gitignore
文件中添加; - 不得提交
node_modules
、dist
等环境或打包文件到仓库; - 每次提交需要注明提交的内容是什么;
commit 的类别,只允许使用下面7个标识。
feat:新功能(feature)
fix:修补bug
docs:文档(documentation)
style: 格式(不影响代码运行的变动)
refactor:重构(即不是新增功能,也不是修改bug的代码变动)
test:增加测试
chore:构建过程或辅助工具的变动
- 合并有冲突时,应在找到对应修改的人一起在本地解决冲突后再提交到仓库;
- 禁止使用
git add *
添加本地文件; - ...
VS code
插件搭配
GitLens — Git supercharged
// 查看git提交历史koroFileHeader
// 文件作者标注、函数注释等eslint/tslint
// 配置js/ts规范自动提示Beautify
// 根据配置文件自动格式化Prettier - Code formatter
// 搭配 Beautify
往期精彩
- 从0搭建Vite + Vue3 + Element-Plus + Vue-Router + ESLint + husky + lint-staged
- 「前端进阶」JavaScript手写方法/使用技巧自查
- JavaScript设计模式之简介及创建型模式
- 公众号打开小程序最佳解决方案(Vue)
- Axios你可能不知道使用方式
「点赞、收藏和评论」
❤️关注+点赞+收藏+评论+转发❤️,创作不易,鼓励笔者创作更好的文章,谢谢🙏大家。