1. 引言
对于一个多人团队来说，制定一个统一的规范是必要的，因为个性化的东西无法产生良好的聚合效果，规范化可以提高编码工作效率，使代码保持统一的风格，以便于代码整合和后期维护。本文档主要描述web项目开发中所使用的html、css、JavaScript等规范，请参与开发相关人员遵循，同时也请各位日后进行补充完善。
2. HTML/CSS规范
2.1 浏览器兼容
根据业务要求而定：
主流程测试：Chrome 30+、IE9+；
完整测试： Chrome 21、IE8+、360浏览器、微信webview/QQ手机浏览器。
2.2 html代码规范
2.2.1声明与编码
1．）html头部声明统一：<!DOCTYPE html>，若发现没统一，即顺手改掉。
2．）页面编码统一：<meta charset="UTF-8">，ie6也支持，无须担心。
2.2.2格式缩进
html编码统一格式化显示，使用一个Tab键进行分层缩进 (2个空格宽度)，使整个页面结构层次清晰，方便阅读和修改。
2.2.3 模块注释
html较大独立模块之间注释格式统一使用：
|
1
2
3
|
<!-- start: XXX模块 -->
…
<!-- end: XXX模块 -->
|
2.2.4标签与属性
1．）html要求所有标签必须关闭。单个标签也必须结束（<br />、<input />、<img />、<hr />）,使用p标签时必须成对使用<p></p>。
2．）所有标签元素和属性建议采用小写。如<BODY>必须写成<body>。
3．）所有html属性必须添加双引号（非单引号）。
|
1
2
3
4
|
// 禁止
<
div
id
=
mainframe
> 或 <
div
id
=
'mainframe'
>
// 推荐
<
div
id
=
"mainframe"
>
|
4．）所有标签必须采用合理嵌套。
|
1
2
3
4
|
// 禁止
<
p
><
b
></
p
></
b
>
// 推荐
<
p
><
b
></
b
></
p
>
|
禁止inline级标签嵌套block级标签，如：<a href="#"><div></div></a>。
5．）所有<、&、>等特殊符号（非标签一部分）用编码表示。< 编码成< ，>编码成>，&编码成&。
6．）img标签中必须添加alt属性。如：<img src="…" alt="logo" />
7．）标签在运用时，应尽量使用语义化标签，如:
|
1
2
|
<
h1
>标题<
h1
>
<
lable
for
=
"user"
>用户名：</
lable
><
input
name
=
"username"
id
=
"user"
/>
|
在语义不明显，既可用div也可用p时，应优先考虑p标签。
2.3 CSS代码规范
2.3.1 CSS引用规范
1．）所有CSS均为外部调用，不得在页面书写任何内部样式或行内样式；
2．）外部调用时，使用link，建议少用@import。
<link rel="stylesheet" href="xxx.css" />
link和@import的最根本区别如下：
A.) 功能不同： link是XHTML标签，除了加载CSS外，还可以定义RSS等其他事务；而@import是CSS内部属性，只能加载CSS。
B.) 变换主题： 也正是由于link是XHTML标签,所以可以用JS控制DOM去改变样式；而@import不行。
C.) 兼容性： link是XHTML标签，无兼容问题；@import是在CSS2.1提出的，低版本的浏览器不支持。
D.) 加载效率： link引用CSS时，在页面载入时同时加载；@import需要页面完全载入以后加载，尤其当用户浏览的网速较慢时,他会看到一个没有风格样式的页面，会有闪动的过程。
E.) 加载顺序： @import会使得CSS整体载入时间变长.并且在IE中会导致文件下载次序被更改,例如放置在@import后面的script文件会在CSS之前被下载。
F.) 使用情况：当然如果需要把CSS进行模块化管理也肯定要用到@import，推荐用@import url(style.css)方式。
2.3.2 CSS注释规范
1．） css头部文档注释( 统一加上@charset声明 )，如下：
|
1
2
3
4
5
6
7
8
9
10
11
|
@charset
"utf-8"
;
/**
* @author : wangwb
* @created : 2013/04/05
* @version : v1.0
* @desc : 小美生活首页
*
* @update : 2014/04/18
* @author : ljlong
* @desc: : 修改说明
*/
|
关于"version"，如果对代码有修改更新version版本号，并添加相关注释。
2．） 内部模块之间注释（建议 @模块英文名，好查找）：
|
1
2
3
4
5
6
7
8
9
|
/* @info 商品信息区
----------------------------------------------------------------*/
.infoArea{}
/* 单行注释 */
.specArea{}
/* @price 商品价格区
----------------------------------------------------------------*/
.price{}
|
2.3.3 CSS书写规范
1．样式书写不做强约，可分行或单行（推荐单行，理由：直观、模块之间分隔鲜明，有全局感）。
2．样式中属性排序规则：先外部 > 再自身 > 后内部，推荐工具( CSScomb )
A.）影响文档流的属性（display, position, float, clear, visibility, table-layout等）
B.）自身盒模型的属性（width, height, margin, padding, border等）
C.）排版相关属性（font, line-height, text-align, text-indent, vertical-align等）
D.）装饰性属性（color, background, opacity, cursor等）
E.）生成内容的属性（content, list-style, quotes等）
2．所有CSS属性和值必须采用小写的形式。如：FONT-SIZE:12PX必须改为font-size:12px；
3．关于css背景图片(关键字：合并，缩写，去引号), 引号不是必须的，而且在某些浏览器上加引号反而出错：
|
1
2
3
4
5
6
7
8
9
|
// 不推荐
.canbox{
background-color
:
#ff6600
;
background-image
:
url
(
"/img/xxx.png"
);
}
// 推荐(合并、去除引号)
.canbox {
background
:
#f60
url
(/img/xxx.png);
}
|
4．属性为0值，去除单位。
|
1
2
3
4
5
6
7
8
|
// 不推荐
.wrap{
margin
:
0px
0px
5px
8px
;
}
// 推荐
.wrap {
margin
:
0
0
5px
8px
;
}
|
5．所有CSS的命名应语义化，如：回复框，.replyBox{…}，禁止用拼音缩写命名，如.hfk{…}。
6．清除浮动时用.clearfix，禁止用无语义的<p style="clear:both"></p>清除。
7．用来显示动态文本输入的地方，样式里必须加上强制英文换行：word-break: break-all; word-wrap: break-word; overflow-x: hidden;
如果要显示省略号加上：text-overflow: ellipsis;
8．上下相邻的两模块尽量避免混用margin-bottom，margin-top，否则会产生重叠现象。
3. JavaScript规范
3.1 JS文件引用
1、引入格式： <script type="text/javascript" src="model.js"></script>
为了格式统一，src属性建议置于后面。
2、引入位置： body标签内最后部（非body外面）, 减少因载入脚本而造成其他页面内容阻塞的问题（js单线程）。
|
1
2
3
4
5
6
|
<
html
>
<
body
>
<
div
>页面内容….</
div
>
<
script
type
=
"text/javascript"
src
=
"model.js"
></
script
>
</
body
>
</
html
>
|
3、引入方式：html页面中禁止直接编写js代码，统一使用<script>外部引用方式，以便打包压缩和缓存。
3.2 JS代码缩进
3.2.1 整体层次
使用 Tab 键进行代码缩进 (4个空格宽度) 。
|
1
2
3
4
5
6
7
|
(
function
() {
var
i = 0;
function
innerFun() {
var
j = 0;
……
}
});
|
3.2.2 局部间隔
运算符（=、==，&&、+/-等）两侧应各空一个格，块级{}左侧也应该空出一格
|
1
2
3
4
5
6
7
8
9
10
11
|
// 不推荐
var
arr=[1,2],str=
'hello'
+
'Lucy'
;
var
myfun=
function
(arg){
//todo…
}
// 推荐
var
arr = [1,2],
str =
'hello'
+
'Lucy'
;
var
myfun =
function
(arg) {
//todo…
}
|
3.3 JS注释规则
3.3.1 文件头部注释
|
1
2
3
4
5
6
7
8
9
10
11
|
/**
* @author : wangwb
* @created : 2013/04/05
* @version : v1.0
* @desc : 当前js模块功能描述
* @e.g. : 方法用例，如：$('.title').tip();
*
* @update : 2014/04/18
* @author : wangdw
* @desc: : 此文件修改说明
*/
|
3.3.2 方法注释及单行注释
1、对于一个较复杂的方法和函数，可用采用多行注释，以便作详情的描述。
|
1
2
3
4
|
/**
* 此方法是用于解析tpl模块
* 通过分析html中结构…
*/
|
2、单行注释
|
1
2
3
4
5
6
|
var
funName =
function
(arg1, arg2) {
this
.arg1 = arg1;
//单行注释说明(上面最好添加一空行)
this
.arg2 = arg2;
};
|
3.4 命名规则
变量名应由 26 个大小写字母（A..Z，a..z），10 个数字（0..9），和“_”（下划线）组成。
1、通常, 使用”驼峰式”写法，对象、函数和实例时尤其如此。
|
1
2
3
4
5
6
|
// 不推荐
var
is_my_object = {};
var
is-my-object = {};
// 推荐
var
isMyObject = {};
|
2、构造函数或类时使用驼峰式大写
|
1
2
3
4
5
6
7
8
9
|
// 不推荐
var
bad =
new
user({
name:
'nope'
});
// 推荐
var
good =
new
User({
name:
'nope'
});
|
3、常量大写，并用下划线分隔，形式如：NAMES_LIKE_THIS
3.5 编码模式
为了规范代码严谨风格，推荐严格模式(Strict Mode)，即总是在模块顶部声明 'use strict';
|
1
2
3
4
5
6
7
|
(
function
(){
'use strict'
;
function
innerFun(){
var
j = 0;
……
}
});
|
严格模式的一大目标是显性的抛出错误，让你能更方便更快的调试一些隐性的错误。
1、防止意外的创建了全局变量。
非严格模式下，为一个未申明的局部变量赋值时会自动创建一个同名的全局变量，这是Js程序中最容易出现的错误之一，在严格模式下这么做会显性的抛出异常。
|
1
2
3
4
|
// 严格模式下会抛出异常
(
function
() {
some =
'foo'
;
}());
|
2、防止函数中的this指针意外指向全局。
非严格模式下，函数中未被定义或为空( null or undefined)的this会默认指向全局环境(global)。
|
1
2
3
4
5
6
7
|
window.color =
'red'
;
function
getColor() {
console.log(
this
.color);
}
// 在严格模式中会报错, 非严格模式中则提示red
getColor();
|
3、防止重名。
当编写大量代码时，对象属性和函数参数很容易一不小心被设置成一个重复的名字。严格模式在这种情况下会显性的抛出错误
//重复的变量名，在严格模式下会报错。
|
1
2
3
|
function
doSomething(value1, value2, value1) {
//code
}
|
//重复的对象属性名，在严格模式下会报错。
|
1
2
3
4
|
var
object = {
foo:
'bar'
,
foo:
'baz'
};
|
4、对只读属性修改/删除时会抛出异常。
ES5中可为对象特定属性设为只读或让整个对象不可修改。 但在非严格模式中尝试修改一个只读属性只会默不做声的失败。
|
1
2
3
4
5
6
7
8
|
var
person = {};
Object.defineProperty(person,
'name'
{
writable:
false
,
value:
'Nicholas'
});
// 在非严格模式时，沉默的失败，在严格模式则抛出异常
person.name =
'John'
;
|
5、不要在全局环境下启用严格模式。
为了兼容第三方代码可能没有为严格模式做好准备而引发的问题，最好把开启严格模式的指令作用于自己独立的模块/函数里。
3.6 推崇建议
—— 变量
声明变量必须加上 var 关键字. 否则变量就会暴露在全局上下文中, 这样很可能会和现有变量冲突。
—— 逗号
不要加多余的逗号，这可能会在IE下引起错误，同时如果多一个逗号某些ES3的实现会计算多数组的长度。
|
1
2
3
4
5
6
7
8
9
10
11
|
// 不推荐
var
hero = {
firstName:
'Kevin'
,
lastName:
'Flynn'
,
};
// 推荐
var
hero = {
firstName:
'Kevin'
,
lastName:
'Flynn'
};
|
—— 分号
如果仅依靠语句间的隐式分隔, 有时会很麻烦.而且有些情况下, 漏掉分号会很危险.
|
1
2
3
4
5
6
7
|
;(
function
(){
var
i = 0;
function
innerFun(){
var
j = 0;
……
}
});
|
—— {},[]
|
1
2
3
4
5
|
// 不推荐
var
item1 =
new
Object(), item2 =
new
Array();
// 推荐
var
item1 = {}, item2 = [];
|
（解释：new关键字的使用 除了在需要实例化一个对象，或罕见的需要延时加载数据的情况外，基本上不需要使用new关键字。在Javascript里分配大量的new变量地址是一项很慢的操作，为了效率起见，应该始终使用对象符号。）
—— 字符串，统一用单引号
|
1
2
3
4
5
|
// 不推荐
var
name =
"Bob Parr"
;
// 推荐
var
name =
'Bob Parr'
;
|
—— === 和 !== 操作符
使用 === 和 !== 操作符会相对好点。== 和 != 操作符会进行类型强制转换。 特别是， 不要将 == 用于与错值比较（false，null，undefined，“”，0，NaN）。
—— 块
|
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
|
// 不推荐
if
(test)
return
false
;
// 推荐
if
(test)
return
false
;
// 或
if
(test) {
return
false
;
}
// 不推荐
function
() {
return
false
; }
// 推荐
function
() {
return
false
;
}
|
—— 不要使用eval()
只用于解析序列化串 (如: 解析 RPC 响应)
eval() 会让程序执行的比较混乱, 当 eval() 里面包含用户输入的话就更加危险.
可以用其他更佳的, 更清晰, 更安全的方式写你的代码, 所以一般情况下请不要使用 eval().
当碰到一些需要解析序列化串的情况下(如, 计算 RPC 响应), 使用 eval 很容易实现.
—— js常见参数命名建议
元素：elem, 参数：arg，对象：obj，数组：arr, 指令：ret，长度：len
4. jQuery性能优化
——总是从ID选择器开始继承
jQuery中最快的筛选器是ID筛选器，这是因为它直接和JS原生方法getElementById()对应。
——在class前使用tag
第二快是tag选择器， 因为它和JS原生方法getElementsByTagName() 对应。jQuery中class选择器是最慢的，因为在IE浏览器下它会遍历所有的DOM节点。
综上两点：
1.) 如果查找$('. class')，应使用$('#id > tag. class')来缩小DOM Tree的搜索范围。
2.) #id 前面不要用tag来修饰。写成$('div#id')会降低性能，因为JS会遍历所有的div元素来查找id为'id'的哪一个节点:
3.) #id1也不需要由#id2来修饰。写成$('#id2 #id1') 是画蛇添足，降低性能。
——缓存JQuery对象
要养成将jquery对象缓存进变量的习惯，避免进行多次查找，另外为了区分普通的JS对象和jQuery对象，建议在变量首字母前加上$符号。如:
|
1
2
3
4
5
6
|
var
$box = $(
'#wrap'
).find(
'.box'
);
$box.addClass(
'class'
);
$.ajax({
$box.html(
'text'
);
});
|
——合理使用链式操作
可以减少对DOM Tree的访问以及代码量。如代码:
|
1
2
3
|
$(
'div'
).addClass(
'className'
).html(
'html code'
).click(
function
(){
alert(1);
});
|
——使用子查询
使用children(), find(), filter()来进行子查询。如代码:
|
1
2
3
|
$(
'div p'
).click(
function
(){
……
});
|
替换成
|
1
2
3
|
$(
'div'
).find(
'p'
).click(
function
(){
……
});
|
——减少DOM操作
当要进行DOM插入时，将所有元素在内存中封装成一个元素，一次性插入。
——自定义数据属性
dom结构上添加自定义属性：
|
1
2
3
4
5
6
7
|
<div id=
"wrap"
data-foo=
"123"
></div>
// 取数据：
$(
'#wrap'
).data(
'foo'
);
// 存数据：
$(
'#wrap'
).data(
'foo'
, {a:1,b:2} );
|
附录
命名规则
1．）所有文件夹命名，如需要两个单词表示的，使用"-"中划线连接（如：img-plug）。
2．）所有文件（.html、.css、.js、图片）命名，如需要两个单词表示的，使用"_"下划线连接符（如：index_info.html）。
3．）所有素材图片应将文件名第一个单词命名为图片分类，第二个单词为图片名称，第三个单词可以是数字或其它内容，以下为图片命名细则：
icon_xxx.gif //图标文件名
btn_xxx.gif //按钮文件名
corner_xxx.gif //边角文件名
banner_xxx.gif //广告条文件名
bg_xxx.gif //背景图片文件名
flash_xxx.gif //flash文件名
temp_xxx.gif //临时测试用文件名