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 //臨時測試用文件名