仓库源文站点原文


layout: post title: 前端规范

tags: [javascript, css, html, f2e, frontend, standard]

说明

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

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

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

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

目录

  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. 性能

<a name="1"></a> 1 代码风格

<a name="1.1"></a> 1.1 缩进

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

<a name="1.2"></a> 1.2 引号

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

<a name="1.3"></a> 1.3 语句结尾 ;

js,css语句结尾添加 ; ,如:

.example {
    margin: 0;
}
var example = {
    foo: 0
};

<a name="1.4"></a> 1.4 { 前空格

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

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

<a name="1.5"></a> 1.5 : 前空格

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

.example {
    margin: 0;
}
var example = {
    foo: 0
};

<a name="1.6"></a> 1.6 , 前空格

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

.example {
    font-family: Arial, sans-serif;
}
var example = [0, 1, 2, 3];

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

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

<a name="1.7"></a> 1.7 ( 前空格

控制语句( 之间有空格,如:

if (true) {
}

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

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

<a name="1.8"></a> 1.8 { 在行末

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

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

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

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

<a name="2"></a> 2 HTML

<a name="2.1"></a> 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">

<a name="2.2"></a> 2.2 JavaScript 和 CSS 文件的引用

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

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

<a name="2.3"></a> 2.3 JavaScript 和 CSS 句柄的使用

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

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

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

<a name="2.4"></a> 2.4 标签关闭

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

<a name="2.5"></a> 2.5 特殊符号

特殊符号采用HTML符号实体

<a name="3"></a> 3 JavaScript

<a name="3.1"></a> 3.1 全局变量

避免使用全局变量

<a name="3.2"></a> 3.2 函数的声明方式

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

<a name="3.3"></a> 3.3 变量的声明方式

<a name="3.4"></a> 3.4 变量的命名

<a name="3.5"></a> 3.5 作用域

<a name="3.6"></a> 3.6 其他

// 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 () {
    //...
});

<a name="4"></a> 4 CSS

<a name="4.1"></a> 4.1 浏览器前缀

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

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

<a name="4.2"></a> 4.2 单位

长度为 0 时须省略单位

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

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

<a name="4.3"></a> 4.3 颜色

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

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

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

<a name="4.4"></a> 4.4 URL

url() 函数中的路径不加引号,如:

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

特殊情况下可以添加双引号,如:

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

<a name="4.5"></a> 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;
}

<a name="4.6"></a> 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 属性,应放在最前面。

<a name="5"></a> 5 文件及目录

<a name="5.1"></a> 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

<a name="5.2"></a> 5.2 文件格式

<a name="5.3"></a> 5.3 压缩和合并

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

<a name="6"></a> 6 命名

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

dpShareboxListItem1boxListItem1_2

<a name="7"></a> 7 注释

<a name="7.1"></a> 7.1 行注释

<a name="7.2"></a> 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

<a name="8"></a> 8 Git 版本管理

  1. 主分支:master,用于发布到 ppe 和线上

  2. 开发分支:feature,可交付的代码,用于持续集成 ci 的构建

  1. 采用 git rebase 合并同一分支上不同人的改动记录,避免产生多余的 commit 记录

  2. 提交 merge request 来将开发分支合并到主分支上。目的是为了增加代码审核流程,以减少上线后的问题

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

<a name="9"></a> 9 版本号

  1. 主版本号:当你做了不兼容的API 修改,

  2. 次版本号:当你做了向下兼容的功能性新增,

  3. 修订号:当你做了向下兼容的问题修正。

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

<a name="10"></a> 10 接口

<a name="11"></a> 11 图片

<a name="12"></a> 12 性能

推荐,不要求

参考