前端规范 - vivaxy's Blog

说明

前端规范是前端开发团队遵循和约定的代码书写规范

遵循本规范可以提高代码的可读性和可维护性

此规范适用于大众点评广告平台前端

斜体表示推荐做法，不做强制规定

代码风格

1.1 缩进

1.2 引号

1.3 语句结尾 ;

1.4 { 前空格

1.5 : 前空格

1.6 , 前空格

1.7 ( 前空格

1.8 { 在行末
HTML

2.1 文件头

2.2 JavaScript 和 CSS 文件的引用

2.3 JavaScript 和 CSS 句柄的使用

2.4 标签关闭

2.5 特殊符号
JavaScript

3.1 全局变量

3.2 函数的声明方式

3.3 变量的声明方式

3.4 变量的命名

3.5 作用域

3.6 其他
CSS

4.1 浏览器前缀

4.2 单位

4.3 颜色

4.4 URL

4.5 缩写

4.6 属性书写顺序
文件及目录

5.1 结构

5.2 文件格式

5.3 压缩和合并
命名
注释

7.1 行注释

7.2 文档注释
Git 版本管理
版本号
接口
图片
性能

1 代码风格

1.1 缩进

html, js, css等一律采用4个空格缩进

1.2 引号

html, json中的引号采用双引号 " ，同时，js中的引号采用单引号 '

1.3 语句结尾 `;`

js，css语句结尾添加 ; ，如：

.example {
    margin: 0;
}

var example = {
    foo: 0
};

1.4 `{` 前空格

css, js中，{ 之间必须包含空格，如：

.example {
}

var example = function(arg1, arg2) {
};

if (true) {
}

1.5 `:` 前空格

css, js中，属性名，对象 与之后的 : 之间不包含空格， : 与之后的值之间包含空格，如：

.example {
    margin: 0;
}

var example = {
    foo: 0
};

1.6 `,` 前空格

多个值 , 前没有空格，后面有空格，如：

.example {
    font-family: Arial, sans-serif;
}

var example = [0, 1, 2, 3];

[] ， () 中的值，开头没有空格， , 前没有空格， , 后一个空格，最后没有空格，如：

var example = function(arg1, arg2) {
    return 'example';
};

1.7 `(` 前空格

控制语句与 ( 之间有空格，如：

if (true) {
}

方法声明的 function 关键字和后面的括号之间有空格

var example = function () {
    return 'example';
};

1.8 `{` 在行末

代码块 ， {} 中的 { 要在行末，而不是行首，如：

// good
var foo = function () {
    return {
        bar : 0
    };
}

js会自动插入分号，当如下情况时，return 值是 undefined

// bad
var foo = function () {
    return
    {
        bar : 0
    };
}

2 HTML

2.1 文件头

文件头采用html5标准 <!DOCTYPE html>

这样能够确保在每个浏览器中拥有一致的展现

head中包含样式表，不包含脚本，包含meta，包含title

head中包含的meta，规定页面编码，禁用用户缩放

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, user-scalable=0">

2.2 JavaScript 和 CSS 文件的引用

css文件引用 <link type="text/css" rel="stylesheet" href="..."> 放置于 </head> 前，不使用 <style> ，便于使用缓存

js文件引用 <script type="text/javascript" src="..."></script> 放置于 </body> 前，不使用 <script> ，便于使用缓存

2.3 JavaScript 和 CSS 句柄的使用

css样式附着于 class="..." ，不使用 style="..."

js操作句柄附着于 class="js-xxx"，遵循github代码规范

绑定的数据使用 data-xxx="..."，横线链接，不使用大写字母，因为html大小写不敏感，最终生成的会是小写的属性值

2.4 标签关闭

不用关闭的标签一律不加 /，如：<br>，<hr>，<input>

2.5 特殊符号

特殊符号采用HTML符号实体

3 JavaScript

3.1 全局变量

避免使用全局变量

3.2 函数的声明方式

用变量形式申明函数，而不是 function

3.3 变量的声明方式

变量在使用前必须通过 var 定义
使用字面量{}、[]替代new Object()、new Array()
不要使用string、bool、number对象类型，即不要调用new String、new Boolean、new Number

3.4 变量的命名

小写开头表示变量，如：topBox，topBoxList，footerCopyright
大写开头表示构造器函数，如：SuperMBox
常量全部大写，如：PIE
方法内的私有变量加前缀 _
构造函数内部的 this 别名采用 _this
jQuery选择器选择的变量使用 $ 开头

3.5 作用域

慎用with，with会引起作用域混乱，作用域查询减缓执行速度
慎用eval

3.6 其他

js改变样式时：尽量改变 class 而不是 style ，手机端使用 classList 代替 className
缓存DOM选择，每次选择都要计算
缓存列表 .length，每次选择都要计算
两次及以上用到的字符串常量，赋值给一个变量，以便在压缩时减少代码体积

// good
var startEvent = 'touchstart';
var elementA = document.querySelector('.example-1');
var elementB = document.querySelector('.example-2');
elementA.on(startEvent, function () {
    //...
});
elementB.on(startEvent, function () {
    //...
});
// uglified
var a = 'touchstart', b = document.querySelector('.example-1'), c = document.querySelector('.example-2');
b.on(a, function () {
    //...
});
c.on(a, function () {
    //...
});

// bad
elementA.on('touchstart', function () {
    //...
});
elementB.on('touchstart', function () {
    //...
});
// uglified
a.on('touchstart', function () {
    //...
});
b.on('touchstart', function () {
    //...
});

字符串转换成数字的时候用 parseInt('08', 10) ，ie8 和三星 webview 下的 bug 会让0开头的字符串变成0
文件开始处添加 'use strict'，启用严格模式
使用canvas动画时，5个元素以内使用css动画，5个以上使用canvas动画
动画选择时，优先使用css3动画
使用requestAnimationFrame动画代替setTimeout

4 CSS

4.1 浏览器前缀

浏览器前缀列表按照下面的顺序

.example {
    -ms-transform: translate(-4px, -4px);
    -moz-transform: translate(-4px, -4px);
    -webkit-transform: translate(-4px, -4px);
    transform: translate(-4px, -4px);
}

4.2 单位

长度为 0 时须省略单位

/* good */
.example {
    padding: 0 5px;
}

/* bad */
.example {
    padding: 0px 5px;
}

4.3 颜色

颜色值可以缩写时，必须使用缩写形式，如：

/* good */
.example {
    background-color: #aca;
}

/* bad */
.example {
    background-color: #aaccaa;
}

颜色值使用小写字母，如：

/* good */
.success {
    background-color: #aca;
}

/* bad */
.success {
    background-color: #aaccaa;
}

颜色值不允许使用命名色值，如：black，green

4.4 URL

url() 函数中的路径不加引号，如：

body {
    background: url(bg.png);
}

特殊情况下可以添加双引号，如：

body {
    background: url("center(240*360).png");
}

4.5 缩写

推荐，不要求

在可以使用缩写的情况下，尽量使用属性缩写，减少代码量，如：

/* good */
.example {
    font: 12px/1.5 arial, sans-serif;
}

/* bad */
.example {
    font-family: arial, sans-serif;
    font-size: 12px;
    line-height: 1.5;
}

4.6 属性书写顺序

推荐，不要求

属性书写顺序：同一 rule set 下的属性在书写时，应按功能进行分组，并以 Formatting Model（布局方式、位置） > Box Model（尺寸） > Typographic（文本相关） > Visual（视觉效果）的顺序书写，以提高代码的可读性。

Formatting Model 相关属性包括：position / top / right / bottom / left / float / display / overflow 等

Box Model 相关属性包括：border / margin / padding / width / height 等

Typographic 相关属性包括：font / line-height / text-align / word-wrap 等

Visual 相关属性包括：background / color / transition / list-style 等

另外，如果包含 content 属性，应放在最前面。

5 文件及目录

5.1 结构

单个html

.
├── index.html        入口页
├── js/               js
│   ├── lib/          js库
│   └── main.js       js入口
└── css/              css
    ├── lib/          css库
    ├── image/        图片
    └── main.css      主css

多个html

.
├── html/
│   ├── welcome.html  页面1
│   └── main.html     页面2
├── js/               js
│   ├── lib/          js库
│   └── main.js       js入口
└── css/              css
    ├── lib/          css库
    ├── image/        图片
    └── main.css      主css

5.2 文件格式

文本文件： UTF-8(无BOM)编码

5.3 压缩和合并

根据项目架构，js, css, html, png需要合并和压缩

6 命名

文件名，文件夹名，项目名，html，css样式名中连接单词使用 - 不使用大写字母，不使用数字开头，如：

dp-share.0.0.1.js，box-list-item-1，mengniu-m-20131230，.top-box

js中连接单词使用驼峰式的变量命名方法，不使用数字开头，数字之间采用 _ ，如：

dpShare，boxListItem1，boxListItem1_2

本规范中只有以上两种命名规范，两者不可混用，不可混淆
相对于驼峰式，下划线连接变量名有更好的可读性，因为下划线很容易就可以当作空格忽略掉，变量名看起来非常像句子，其中可以包含大小写数字等字符。但是js中很多原声方法都是驼峰式，为了统一，还是使用了驼峰式变量名。

7 注释

7.1 行注释

/* css 注释 */

// js 单行注释，可以使用多行注释，但是不要在单行中使用多行注释的方式去注释（可能和正则混淆）

7.2 文档注释

推荐，不要求

js 文档

/**
 * bla
 * foo
 * bar
 * @file 文件说明
 * @author 开发者姓名(开发者邮箱)
 * @since 新建时间
 * @modified 修改时间
 * @namespace 命名空间
 * @class //标记类
 * @extends 描述继承关系
 * @param {string} p1 参数1的说明
 * @return 返回值描述
 * @inner //标记内部函数，外部无法访问
 * @override //重写父类中的方法
 * @event 事件描述
 * @fires Select#change 广播事件
 * @const //标记常量
 * @type {string} //变量类型
 */

参见JSDoc

8 Git 版本管理

分支命名

主分支：master，用于发布到 ppe 和线上
开发分支：feature，可交付的代码，用于持续集成 ci 的构建

分支合并

采用 git rebase 合并同一分支上不同人的改动记录，避免产生多余的 commit 记录
提交 merge request 来将开发分支合并到主分支上。目的是为了增加代码审核流程，以减少上线后的问题

删除分支

code 上提 merge request 时，勾选删除源分支。

9 版本号

版本格式：主版本号.次版本号.修订号

主版本号：当你做了不兼容的API 修改，
次版本号：当你做了向下兼容的功能性新增，
修订号：当你做了向下兼容的问题修正。

先行版本号及版本编译信息可以加到“主版本号.次版本号.修订号”的后面，作为延伸

10 接口

取数据的接口用 GET ，提交数据的接口使用 POST
需要及时更新的数据，使用 GET 方法，在参数后添加时间戳 &_={timestamp}

11 图片

移动端图片宽度不大于640
避免重设图片大小，重设图片大小是指在html、css、js，多次重设图片大小会引发图片的多次重绘，影响性能，默认在css中设置图片大小，当css中无法设置大小时，使用js
图片尽量避免使用DataURL，DataURL图片没有使用图片的压缩算法文件会变大，并且要解码后再渲染，加载慢耗时长
纯颜色，三角形，logo，使用css, svg, iconfont代替图片

12 性能

推荐，不要求

移动端三秒种渲染完成首屏，首屏加载3秒完成或使用Loading。基于联通3G网络平均338KB/s(2.71Mbps），所以首屏资源不应超过1014KB，多余的资源采用loading。
移动端减少HTTP请求，首次加载同时请求数不能超过4个。手机浏览器同时响应请求为4个请求（Android支持4个，iOS 5后可支持6个）
异步加载第三方资源：第三方资源不可控会影响页面的加载和显示，因此要异步加载第三方资源

说明

目录

1 代码风格

1.1 缩进

1.2 引号

1.3 语句结尾 ;

1.4 { 前空格

1.5 : 前空格

1.6 , 前空格

1.7 ( 前空格

1.8 { 在行末

2 HTML

2.1 文件头

2.2 JavaScript 和 CSS 文件的引用

2.3 JavaScript 和 CSS 句柄的使用

2.4 标签关闭

2.5 特殊符号

3 JavaScript

3.1 全局变量

3.2 函数的声明方式

3.3 变量的声明方式

3.4 变量的命名

3.5 作用域

3.6 其他

4 CSS

4.1 浏览器前缀

4.2 单位

4.3 颜色

4.4 URL

4.5 缩写

4.6 属性书写顺序

5 文件及目录

5.1 结构

5.2 文件格式

5.3 压缩和合并

6 命名

7 注释

7.1 行注释

7.2 文档注释

8 Git 版本管理

9 版本号

10 接口

11 图片

12 性能

参考

1.3 语句结尾 `;`

1.4 `{` 前空格

1.5 `:` 前空格

1.6 `,` 前空格

1.7 `(` 前空格

1.8 `{` 在行末