编程规约

编程规约

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

一、命名规范

: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 语义化标签,避免每一个节点都是

或者

2.5 引号

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

  • :white_check_mark:
  • :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;
}

推荐:white_check_mark:

.roof {
    margin-top : 100px;
}
.important { 
    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级的嵌套。应该重新评估。这可以避免大量的嵌套规则

推荐 :white_check_mark:

.main-title {
    .name {
        ...
    }
}

不推荐 :white_check_mark:

.main { 
    .title { 
        .name {
            ...
        }
    }
}

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

推荐 :white_check_mark:

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

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: '按降序排序'
}

你可能感兴趣的:(编程规约)