现代软件架构的复杂性需要协同开发完成,如何高效地协同呢?无规矩不成方圆,无规范难以协同,比如,制订交通法规表面上是要限制行车权,实际上是保障公众的人身安全,试想如果没有限速,没有红绿灯,谁还敢上路行驶。对软件来说,适当的规范和标准绝不是消灭代码内容的创造性、优雅性,而是限制过度个性化,以一种普遍认可的统一方式一起做事,提升协作效率,降低沟通成本。代码的字里行间流淌的是软件系统的血液,质量的提升是尽可能少踩坑,杜绝踩重复的坑,切实提升系统稳定性,码出质量。
编程规约
统一要求
基本规范
- 所有类名、id名、方法名等涉及到名称的,统一使用驼峰命名,命名要具有业务意义,语义化,简洁明了
- 代码中不得出现警告,无用测试代码,无用大量console
- 代码中不得出现数字(插件除外)
- 结构(html),表现(css),行为(js)代码需分离
基本原则
- 代码力求简洁,不要写大量重复的逻辑代码(公共方法需封装,公共样式提取到公共样式中)
- 代码要有可读性,函数和元素命名要具有业务意义,关键业务要有详细的注释
- 代码要有扩展性,要尽可能适应未来的业务变化
- 代码要有通用性,一个方法只专注于该方法需要做的事情(对外暴露相应的参数),一个模块只专注于该模块范围内的事情(对外暴露相应的接口)
- 代码要有必要的注释,注释要简单清晰语义明确,并及时更新
html规范
书写规则
- Html代码大小写
HTML标签名、类名、标签属性和大部分属性值统一用小写
统一以小写字母开头,小写字母、下划线和数字组成
<div class="demo_class"></div> // 推荐
<div class="demo"></div> // 不推荐,命名太简单,应该语义化
<div class="demoClass"></div> // 不推荐,保持小写
- 元素属性
属性值使用双引号语法,js用单引号,
尽量不在html中写css样式,尽量使用class属性写到css中
<a href="" class="demo_class"></a> // 推荐
<div style="width: 10px; height: 10px;"></div> // 不推荐
- 特殊字符引用
不得使用‘>’和‘<’特殊字符,浏览器会将它们作为标签解析,若要正确显示,在 HTML 源代码中使用字符实体
<a href="#">more>></a> // 不推荐
- 代码嵌套
每个块级元素独占一行,内联元素可选
css规范
代码格式化
- 样式选择器,属性名,属性值关键字全部使用小写字母书写,属性字符串允许使用大小写
- 每个属性声明末尾都要加分号;
- css属性值需要用到引号时,统一使用双引号
- 尽量不要用固定的宽高,多使用padding和margin
- 尽量少用通用选择器
- 不使用ID选择器
- 不使用无具体语义定义的标签选择器
- 尽量少用!Important
代码可读性
- 左括号与类名之间一个空格,冒号与属性值之间一个空格
- 逗号分隔的取值,逗号之后一个空格
box-shadow: 1px 1px 1px #333, 2px 2px 2px #ccc; // 推荐
- 不要为0指明单位
margin: 0px 10px; // 不推荐
margin: 0 10px; // 推荐
- 避免嵌套层级过深
// 不推荐
.main {
.title{
.name {
color: red
}
}
}
// 推荐
.main-title {
.name {
color: red
}
}
属性书写顺序
- 建议遵循以下顺序
- 布局定位属性:display / position / float / clear / visibility / overflow(建议 display 第一个写,毕竟关系到模式)
- 自身属性:width / height / margin / padding / border / background
- 文本属性:color / font / text-decoration / text-align / vertical-align / white- space / break-word
- 其他属性(CSS3):content / cursor / border-radius / box-shadow / text-shadow / background:linear-gradient 等
- 如果是单个页面需要改公共css或者插件样式,请一定在单个页面的样式中改,坚决不能修改插件源码,js文件同理
- 当属性存在兼容问题的,兼容多个浏览器时,将标准属性写在底部
JS规范
- 尽量不要定义全局变量,否则很容易造成全局变量污染。
- 变量使用let,常量使用const
- 尽量使用=== 和 !==
- 尽量使用箭头函数
- 多使用map、find、filter、reduce、every、some等便利数组,代替for-in和for-of,使代码简洁且语义清晰
- 减少不必要的if语句的嵌套
const num = 1
let flag = false
// 不推荐
if(num === 1) {
flag = true
} else {
flag = false
}
// 二选一条件下推荐
num === 1 ? flag = true : flag = false
// 简单判断推荐
flag = num === 1
- 多使用es6及以上的规范
es6新特性 点击查看 - 永远不要直接使用 undefined 进行变量判断,使用 typeof 和字符串’undefined’对变量进行判断
if (person === undefined) { ...}
if (typeof person === 'undefined') { ...}
vue规范
- 公共组件应该都放到components文件夹下
- 标签语义化,避免清一色的div元素
- DOM的层级数尽可能少,优化渲染速度
- 尽量少使用br标签换行
- 多使用布局flex
- 为v-for设置Key值。(不建议 用index 作为 key,和没写基本上没区别,因为不管你数组的顺序怎么颠倒,index 都是 0, 1, 2 这样排列,导致 Vue 会复用错误的旧子节点,做很多额外的工作)
- 规避v-if和v-for用在一起或者增加一层,使用filter等方法过滤
- 使用scoped关键字,约束样式生效的范围
- 相同的卡片布局,首先整合数据,尽量使用循环方式去增加,避免变更多处的问题。
- data函数中,非常见单词要加注释
- methods中,每个 method 必须添加注释
- api 目录的接口 js 文件必须加注释
- 公共组件必须加注释
- template 必须加注释,若文件较大添加 start end 注释
命名规范
文件命名
- index.js 或者 index.vue不变
- 属于组件或类的,统一使用大驼峰的(PascalCase)命名规范
- 其他非组件或类的,统一使用小驼峰的(kebabCase)命名规范
变量函数
变量函数等命名必须语义化切严谨,尽量不使用简单通用的单词,变量函数使用小驼峰,常量使用全大写
不要嫌弃命名太长
// 不推荐
let type = [] // 命名太过简单
// 推荐
const LOCATION_PERMISSION = 1 // 定义常量
let setLocationPermission = 1 // 定义变量
const getLocationPermission = () => {} // 定义函数
const _temp = 1 // 私有化属性
增删查改,详情统一使用如下 5 个单词,不得使用其他(目的是为了统一各个端)
add / update / delete / detail / get
函数方法常用的动词在文章最后
git管理
分支管理
- master分支,用于生产环境更新
- develop分支,用于测试环境更新,和日常开发
- 私有化master分支,例如:xianghe_master,用于祥和社区私有化生产环境更新
- 私有化develop分支,例如:xianghe_develop,用于祥和社区私有化测试环境更新
- 临时分支,用于音轨的一些特定的版本开发(验证ok后,合并到主分支,并删除该分支)
临时分支命名
- 从哪个主分支创建的分支
- 分支的主要目的
- feature - 功能、需求
- fixbug - bug修复
- 创建日期 mm.dd
- 创建人(方便追溯)
例如:积分商城开发新需求3.0版本
develop-feature3.0-10.28-your name
附: 函数方法常用的动词:
get 获取/set 设置,
add 增加/remove 删除
create 创建/destory 移除
start 启动/stop 停止
open 打开/close 关闭,
read 读取/write 写入
load 载入/save 保存,
create 创建/destroy 销毁
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 移除,
add 加入/append 添加
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 折叠
begin 起始/end 结束,
start 开始/finish 完成
enter 进入/exit 退出,
abort 放弃/quit 离开
obsolete 废弃/depreciate 废旧,
collect 收集/aggregate 聚集