编程规约

规范的目的是为了编写高质量的代码，让你的团队成员每天得心情都是愉悦的，大家在一起是快
乐的

一、命名规范

: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 大写

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Document</title>
</head>
<body>
  
</body>
</html>

2.2 缩进

缩进使用 2 个空格(一个tab)，嵌套的节点应该缩进

2.3 分块注释

在每一个块状元素、列表元素、表格元素后，加上一对 HTML 注释

2.4 语义化标签

使用 HTML5 语义化标签，避免每一个节点都是 <div> 或者 <p>

2.5 引号

使用双引号""而不是单引号''

<div class="list"></div> :white_check_mark:
<div class='list'></div> :negative_squared_cross_mark:

三、CSS规范

类名使用 kebab-case
id 采用 camel-case
预处理语言中的变量、函数、混合、placeholder采用 camel-case

3.1 命名

id 或者 class 名称 反映元素目的与用途，或者其他通用的名称

不推荐:negative_squared_cross_mark:

.mr100 {    
  margin-top : 100px;
}
.red { 
    color : red;
}

3.2 选择器

css 选择器避免使用标签名

从结构、表现、行为分离情况看，应该避免在css中出现 HTML标签，并且在 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:

四、预处理语言规范

用 scss 举例

4.1 代码组织

公共文件存放

应该将公共文件存放在 style/scss/common 文件夹中。

例如 style/scss/common/color.scss

组织样式文件

应该按照以下顺序组织

@import
变量命名
样式声明

@import '~style/mixins/size.scss'
$defaultTextColor : #333;

.page { 
    ...
}

4.2 避免嵌套层级过多

嵌套深度限制在3级，超过或者为4级的嵌套。应该重新评估。这可以避免大量的嵌套规则

五、JavaScript规范

5.1 命名

变量命名

采用小写 camel-case ，代码中的命名不能以下划线，也不能以下划线或者$符号结束

_name/name_/name$ :negative_squared_cross_mark:

方法名、参数名、成员变量

统一使用小写 camel-case

localValue/getHttpMessage()/inputUserId :white_check_mark:

其中，method 方法必须是动词 + 名词形式

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

必须优先使用 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 条件判断和循环最多三层

能用三目运算符则使用三目运算符
如果超过三层请抽象为函数

不推荐 :negative_squared_cross_mark:

if(item.status == 2 && item.statusName === '正在直播' && localStorage.get('SHOW_DIDALOG')) { 
    ...
}

5.8 this引用命名

对于上下文的 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). 配置类、选项类

主要指组件功能的开启与关闭、功能属性的配置

withXx 表示组件在基本功能形态的其他功能，例如高级功能
enableXx 表示组件某些功能的开启
allowXx 表示功能属性的配置
noXx 表示建议功能，用于配置不建议开启的功能

{
  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.'
}

除了上述这些带有特定的前置介词、动词以外还有一些语义上有疑问性质的组合也作为Boolean命名的参考

{
  virtualScroll: '是否启用虚拟滚动模式',
  unlinkPanels: '在范围选择器里取消两个日期面板之间的联动',
  validateEvent: '输入时是否触发表单的校验'
}

(4). 数组命名

数组命名推荐复数命名，还有就是名词和具有列表意思的单词组合见的词汇有 options, list, maps, nodes, entities, collection 等。

{
  users: '用户列表',
  userList: '用户列表',
  tabOptions: '选项卡选项',
  stateMaps: '状态映射表',
  selectedNodes: '选中的节点',
  btnGroup: '按钮组',
  userEntities: '用户实体'
}

(5). 选项元素、下拉元素命名

主要针对的是在下拉选择框、选项卡元素、Radio、Checkbox等数据源每个选项数据的命名。常见的词汇有：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). 事件处理

事件处理函数是前端平时用到最多的，包括浏览器原生事件、异步事件和组件自定义事件。例如最为常见的

onXx
onXxClick
handleXx
handleXxChange

这里如何在二者之间选择，可以从二方面来归类。

原生事件采用 onXx
自定义事件使用 handleXx。
事件主动监听采用 onXx
被动处理使用 handleXx。

从实践及三大主流框架的文档关于事件部分的内容来看，推荐使用 handleAction 这种方式，而在表单提交的时候通常采用onSubmit函数。

但还有一些约定俗称的例子

{
  onSubmit: '提交表单',
  handleSizeChange: '处理分页页数改变',
  handlePageChange: '处理分页每页大小改变',
  onKeydown: '按下键'
}

(2).异步处理

fetch/get 获取数据
update / delete / remove /create 操作数据

6.3 数据加工

这类场景在处理列表的时候经常会碰到，比如排序、过滤、添加额外的字段、根据ID和索引获取特定数据等

(1). 根据特定属性获取对象

这里可以参考DOM方法的命名，比如：getElememtById()、getElementsByTagName()、getElementsByClassName() 和 getElementsByName()

{
  getItemById: '根据ID获取数据元素',
  getItemsBySelected: '根据传入的已选列表ID来获取列表全部数据',
  queryUserByUid: '根据UID查询用户'
}

(2). 格式化数据

这里的格式化操作包括排序、调整数据结构、过滤数据、添加属性。命名通常使用 formatXx, convertXx, inverseXx, toggleXx, parseXx, flatXx, 也可以结合数组的一些操作方法来命名，比如 sliceXx, substrXx, spliceXx, sortXx, joinXx 等来命名。

{
  formatDate: '格式化日期',
  convertCurrency: '转换货币单位',
  inverseList: '反转数据列表',
  toggleAllSelected: '切换所有已选择数据状态',
  parseXml: '解析XML数据',
  flatSelect: '展开选择数据',
  sortByDesc: '按降序排序'
}

编程规约

编程规约

一、命名规范

1.1 项目命名

1.2 目录命名

1.3 JS、CSS、SCSS、HTML、PNG文件命名

1.4 代码命名严谨性

二、HTML规范

2.1 HTML类型

2.2 缩进

2.3 分块注释

2.4 语义化标签

2.5 引号

三、CSS规范

3.1 命名

3.2 选择器

css 选择器避免使用标签名

使用直接子选择器

使用缩写属性

省略 0 后面的单位

避免使用标签选择器污染全局样式

四、预处理语言规范

4.1 代码组织

公共文件存放

组织样式文件

4.2 避免嵌套层级过多

五、JavaScript规范

5.1 命名

变量命名

方法名、参数名、成员变量

常量命名

5.2 代码格式

缩进

空行

引号

5.3 对象

使用字面量

5.4 优先使用es6

5.5 括号

5.6 undefined判断

5.7 条件判断和循环最多三层

5.8 this引用命名

5.9 慎用console.log

六、命名参考

6.1 变量命名

(1). 表示可预见、进行中的状态

(2). 属性状态类

(3). 配置类、选项类

(4). 数组命名

(5). 选项元素、下拉元素命名

(6). 激活项命名

(7). 临时数据、比对数据命名

6.2 函数命名

(1). 事件处理

(2).异步处理

6.3 数据加工

(1). 根据特定属性获取对象

(2). 格式化数据

推荐阅读更多精彩内容