编程规约
规范的目的是为了编写高质量的代码, 让你的团队成员每天得心情都是愉悦的, 大家在一起是快
乐的
一、命名规范
:snake: kebab-case 指短横线命名法,而 camel-case 指驼峰命名法
1.1 项目命名
全部采用小写方式,用-
分割
-
mall-management-system
:white_check_mark: -
mall_management_system、mallMangementSystem
:negative_squared_cross_mark:
1.2 目录命名
全部采用小写,以中划线分割,有复数结构时,要采用复数命名法 ,缩写是不用复数的
-
scripts/styles/components/images/demo-styles/img/doc
:white_check_mark: -
script/demo_scripts/demoStyles/imgs/docs
:negative_squared_cross_mark:
Vue 项目中目录使用 kebab-case 命名
-
head-search / page-loading
:white_check_mark: -
HeadSearch / PageLoading
:negative_squared_cross_mark:
1.3 JS、CSS、SCSS、HTML、PNG文件命名
全部用 kebab-case 命名
-
render-dom.js / signup.css /index.html / company-logo.png
:white_check_mark: -
renderDOM.js / UserMangement.html
:negative_squared_cross_mark:
1.4 代码命名严谨性
代码命名严禁使用拼音与英文混合的方式,更不允许使用中文的方式。
-
hennan/luoyang/rmb
等国际通用名称,可视为英文 :white_check_mark: -
DaZhePromotion/getPingfenByName
:negative_squared_cross_mark:
杜绝不规范的缩写,避免望文生意。
-
AbstractClass -> AbsClass / condition -> condi
:negative_squared_cross_mark:
二、HTML规范
适用 Vue template
2.1 HTML类型
使用 HTML5 的文档类型声明 ,文档中需要声明如下元素
- 规定字符编码
- IE 兼容模式
- 规定字符编码
- doctype 大写
Document
2.2 缩进
缩进使用 2 个空格(一个tab),嵌套的节点应该缩进
2.3 分块注释
在每一个块状元素、列表元素、表格元素后,加上一对 HTML 注释
2.4 语义化标签
使用 HTML5 语义化标签,避免每一个节点都是 使用双引号 id 或者 class 名称 反映元素目的与用途,或者其他通用的名称 不推荐:negative_squared_cross_mark: 推荐:white_check_mark: 从结构、表现、行为分离情况看,应该避免在css中出现 HTML标签 ,并且在 css 选择器中出现标签名会存在潜在的问题 用 scss 举例 应该将公共文件存放在 例如 应该按照以下顺序组织 嵌套深度限制在3级,超过或者为4级的嵌套。应该重新评估。这可以避免大量的嵌套规则 推荐 :white_check_mark: 不推荐 :white_check_mark: 采用小写 camel-case ,代码中的命名不能以下划线,也不能以下划线或者$符号结束 统一使用 小写 camel-case 其中,method 方法必须是 动词 + 名词 形式 特别地,增删改查必须使用如下单词 另外,常见的动词如下 : 全部使用大写,单词用下划线隔开。力求语义完整清楚,不要嫌名字长 使用两个空格进行缩进 不同逻辑、不同语义、不同业务的代码之间插入一个空行分隔来提高可读性。 统一使用 使用字面量格式创建对象 必须优先使用 es6 新增的语法糖与函数。这将简化你的程序。 下面关键字后必须跟括号,哪怕代码内容只有一行。 永远不要使用 不推荐 :negative_squared_cross_mark: 推荐 :white_check_mark: 对于上下文的 this 引用只能用 因为 可见性例如 推荐命名方式 用于描述视图的功能属性,写法和用法比较固定 主要指组件功能的开启与关闭、功能属性的配置 除了上述这些带有特定的前置介词、动词以外还有一些语义上有疑问性质的组合也作为Boolean命名的参考 数组命名推荐复数命名,还有就是名词和具有列表意思的单词组合 见的词汇有 主要针对的是在下拉选择框、选项卡元素、Radio、Checkbox等数据源每个选项数据的命名。常见的词汇有: 函数命名的方式常常是和业务逻辑耦合在一起的,但是在命名规则上也有一些常见的模式可以遵循。 事件处理函数是前端平时用到最多的,包括浏览器原生事件、异步事件和组件自定义事件。例如最为常见的 这里如何在二者之间选择,可以从二方面来归类。 从实践及三大主流框架的文档关于事件部分的内容来看,推荐使用 但还有一些约定俗称的例子 这类场景在处理列表的时候经常会碰到,比如排序、过滤、添加额外的字段、根据ID和索引获取特定数据等 这里可以参考DOM方法的命名,比如:getElememtById()、getElementsByTagName()、getElementsByClassName() 和 getElementsByName() 这里的格式化操作包括排序、调整数据结构、过滤数据、添加属性。命名通常使用 formatXx, convertXx, inverseXx, toggleXx, parseXx, flatXx, 也可以结合数组的一些操作方法来命名,比如 sliceXx, substrXx, spliceXx, sortXx, joinXx 等来命名。
2.5 引号
""
而不是单引号''
:white_check_mark:
:negative_squared_cross_mark:
三、CSS规范
3.1 命名
.mr100 {
margin-top : 100px;
}
.red {
color : red;
}
.roof {
margin-top : 100px;
}
.important {
color : red;
}
3.2 选择器
css 选择器避免使用标签名
使用直接子选择器
.content>.title
:white_check_mark:.content .title
:negative_squared_cross_mark:使用缩写属性
margin : 100px 100px 0 0
:white_check_mark:margin-top:100px;margin-right:100px
:negative_squared_cross_mark:省略 0 后面的单位
margin-top : 0
:white_check_mark:margin-top : 0px
:negative_squared_cross_mark:避免使用标签选择器污染全局样式
.header { ... }
:white_check_mark:header { ... }
:negative_squared_cross_mark:四、预处理语言规范
4.1 代码组织
公共文件存放
style/scss/common
文件夹中。style/scss/common/color.scss
组织样式文件
@import '~style/mixins/size.scss'
$defaultTextColor : #333;
.page {
...
}
4.2 避免嵌套层级过多
.main-title {
.name {
...
}
}
.main {
.title {
.name {
...
}
}
}
五、JavaScript规范
5.1 命名
变量命名
_name/name_/name$
:negative_squared_cross_mark:方法名、参数名、成员变量
localValue/getHttpMessage()/inputUserId
:white_check_mark:
saveShopCarData / openShopCarInfoDialog
:white_check_mark:save / open / show / go
:negative_squared_cross_mark:add / update / delete / detail / get
get 获取/set 设置,
add 增加/remove 删除,
create 创建/destory 销毁,
start 启动/stop 停止,
open 打开/close 关闭,
read 读取/write 写入,
load 载入/save 保存,
begin 开始/end 结束,
backup 备份/restore 恢复,
import 导入/export 导出,
split 分割/merge 合并
get 获取/set 设置,
add 增加/remove 删除,
create 创建/destory 销毁,
start 启动/stop 停止,
open 打开/close 关闭,
read 读取/write 写入,
load 载入/save 保存,
begin 开始/end 结束,
backup 备份/restore 恢复,
import 导入/export 导出,
split 分割/merge 合并
常量命名
LOAD_ERROR_TYPE
:white_check_mark:LOAD_TYPE
:negative_squared_cross_mark:5.2 代码格式
缩进
空行
引号
''
创建字符串5.3 对象
使用字面量
let user = {}
5.4 优先使用es6
5.5 括号
if/else/for/while/do/switch/try/catch/finally/with
5.6 undefined判断
undefined
直接进行变量判断;而是使用 typeof
结合字符串undefined
判断
if(typeof person === 'undefined') {}
:white_check_mark:if(person === undefined)
:negative_squared_cross_mark:5.7 条件判断和循环最多三层
if(item.status == 2 && item.statusName === '正在直播' && localStorage.get('SHOW_DIDALOG')) {
...
}
function checkShowDialog(item) {
return item.status == 2 && item.statusName === '正在直播' && localStorage.get('SHOW_DIDALOG')
}
if(checkShowDialog(item)) {
...
}
5.8 this引用命名
self
进行命名5.9 慎用console.log
console.log
大量使用会有性能问题,所以在非webpack项目中谨慎使用 log 功能六、命名参考
6.1 变量命名
(1). 表示可预见、进行中的状态
v-show
,进行中说明某种状态持续进行中js +动词 (现在进行时)
{
isShow: '是否显示',
isVisible: '是否可见',
isLoading: '是否处于加载中',
isConnecting: '是否处于连接中',
isValidating: '正在验证中',
isRunning: '正在运行中',
isListening: '正在监听中'
}
(2). 属性状态类
{
disabled: '是否禁用',
editable: '是否可编辑',
clearable: '是否可清除',
readonly: '只读',
expandable: '是否可展开',
checked: '是否选中',
enumberable: '是否可枚举',
iterable: '是否可迭代',
clickable: '是否可点击',
draggable: '是否可拖拽'
}
(3). 配置类、选项类
{
withTab: '是否带选项卡',
withoutTab: '不带选项卡',
enableFilter: '开启过滤',
allownCustomScale: '允许自定义缩放',
shouldClear: '是否清除',
canSelectItem: '是否能选中元素',
noColon: '不显示label后面的冒号',
checkjs: '检查js',
emitBOM: 'Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.'
}
{
virtualScroll: '是否启用虚拟滚动模式',
unlinkPanels: '在范围选择器里取消两个日期面板之间的联动',
validateEvent: '输入时是否触发表单的校验'
}
(4). 数组命名
options, list, maps, nodes, entities, collection
等。{
users: '用户列表',
userList: '用户列表',
tabOptions: '选项卡选项',
stateMaps: '状态映射表',
selectedNodes: '选中的节点',
btnGroup: '按钮组',
userEntities: '用户实体'
}
(5). 选项元素、下拉元素命名
title, name, key, label, field, value, id, children, index, nodes
等。// 最常见组合
{
title: '标题',
value: 'ID值'
}
// 组合二
{
label: '标签名',
value: 'ID值'
}
// 组合三
{
name: '元素名',
id: 'ID值'
}
// 组合四
{
field: '字段',
value: '标识',
index: '索引'
}
(6). 激活项命名
{
activeTab: '当前选中选项卡',
currentPage: '当前页',
selectedData: '当前选项中数据',
}
(7). 临时数据、比对数据命名
{
swapData: '临时交换数据',
tempData: '临时数据',
dataSnapshot: '数据快照'
}
6.2 函数命名
(1). 事件处理
handleAction
这种方式,而在表单提交的时候通常采用onSubmit
函数。{
onSubmit: '提交表单',
handleSizeChange: '处理分页页数改变',
handlePageChange: '处理分页每页大小改变',
onKeydown: '按下键'
}
(2).异步处理
6.3 数据加工
(1). 根据特定属性获取对象
{
getItemById: '根据ID获取数据元素',
getItemsBySelected: '根据传入的已选列表ID来获取列表全部数据',
queryUserByUid: '根据UID查询用户'
}
(2). 格式化数据
{
formatDate: '格式化日期',
convertCurrency: '转换货币单位',
inverseList: '反转数据列表',
toggleAllSelected: '切换所有已选择数据状态',
parseXml: '解析XML数据',
flatSelect: '展开选择数据',
sortByDesc: '按降序排序'
}