Teambiz中前臺開發規范
作者：何楊
撰寫日期：2012年3月9日
版本：1.00
更新日期：
第一部分：規范目的
為了提高團隊協作效率, 提高前臺頁面文件的可讀性，可維護性和一致性，從而方便前后臺人員維護管理, 輸出高質量的文檔, 特制訂此文檔.
本規范文檔一經討論確認, 前端開發人員必須按本文檔規范進行前臺頁面開發. 如在執行過程中，文檔確有不合時宜的地方，可及時提出, 經會議討論后決定可以更改此文檔后再執行。
第二部分：基本準則
符合web標準, 語義化html, 結構表現行為分離, 兼容性優良. 頁面性能方面, 代碼要求簡潔明了有序, 盡可能的減小服務器負載, 保證最快的解析速度.
程序員應該書寫項目組所有人都可以看的懂的代碼. 簡潔易懂是一種美德. 在你們編寫程序時必須時刻為用戶著想, 為服務器著想.
第三部分：前臺分離制度
我們認為，前臺頁面混亂的根源之一在于一個頁面擔負了太多的任務。因此，必須把頁面的結構，樣式，行為三部分解構開來，這三部分的命名如下：
| 類型 | 名稱 | 擔負任務 | 說明 |
| JSP | *.jsp | 網頁的結構 | 以下簡稱JSP |
| CSS | style.css | 網頁樣式 | 以下簡稱CSS |
| JS | javascript.jsp | 網頁行為 | 以下簡稱JS |
第四部分：JSP文件書寫規范
1. 文檔類型聲明及編碼: 統一為html5聲明類型<!DOCTYPE html>; 編碼統一為<meta charset="utf-8" />, 書寫時利用IDE實現層次分明的縮進;
2. 非特殊情況下樣式文件必須外鏈至<head>...</head>之間;非特殊情況下JavaScript文件必須外鏈至頁面底部;
3. 引入樣式文件或JavaScript文件時, 須略去默認類型聲明, 寫法如下:
<link rel="stylesheet" href="..." />
<style>...</style>
<script src="..."></script>
4. 所有編碼均遵循xhtml標準, 標簽 & 屬性 & 屬性命名 必須由小寫字母及下劃線數字組成, 且所有標簽必須閉合, 包括br (<br />), hr(<hr />)等; 屬性值必須用雙引號包括;
5. 充分利用無兼容性問題的html自身標簽, 比如span, em, strong, optgroup, label,等等; 需要為html元素添加自定義屬性的時候, 首先要考慮下有沒有默認的已有的合適標簽去設置, 如果沒有, 可以使用須以"data-"為前綴來添加自定義屬性，避免使用"data:"等其他命名方式;
6.結構化JSP,示例如下
<div id=”mainMenu”>
<ul>
<li><a href=”#”>首頁</a></li>
<li><a href=”#”>介紹</a></li>
<li><a href=”#”>服務</a></li>
</ul>
</div>
很多編譯器提供了格式化的工具對代碼整形,希望多加利用.如果機器整形效果不如手動整形，請進行手動整形.
6. 盡可能減少冗余的div嵌套, 如<div class="box"><div class="welcome">歡迎訪問XXX, 您的用戶名是<div class="name">用戶名</div></div></div>完全可以用以下代碼替代: <div class="box"><p>歡迎訪問XXX, 您的用戶名是<span>用戶名</span></p></div>;
9. 書寫鏈接地址時, 必須避免重定向，例如：, 即須在URL地址后面加上“/”；
10. 在頁面中盡量避免使用style屬性,即style="…"; 如果需要初始化某元素的style屬性，請在CSS中設置或是在JS函數window.onload中設置。
11. 能以背景形式呈現的圖片, 盡量寫入css樣式中;
12. 給區塊代碼及重要功能(比如表格展現)加上注釋, 方便后臺添加功能;
第四部分：CSS文件書寫規范
1. 文件編碼統一為utf-8;
2.結構化CSS,如下
html,body {
height:100%;
margin:0px;
font-size:12px;
}
body{
margin-top: 5px;
margin-bottom: 5px;
margin-left: 5px;
margin-right: 5px;
text-align: center;
font-size: 12px;
font-family:"宋體","Tahoma";
background:#ffffff;
overflow-y:hidden;
}
img{
border:0px;
}
#header{
margin:0px;
padding:0px;
border:0px solid #00ff00;
width:100%;
height:75px;
overflow:hidden;
}
2. 協作開發及分工: 架構師會根據各個模塊, 同時根據頁面相似程序, 事先寫好大體框架文件, 分配給前端人員實現內部結構&表現&行為; 共用css文件style.css由架構師書寫, 協作開發過程中, 每個頁面請務必都要引入,此文件不可隨意修改;
3. class與id的使用: id是唯一的并是父級的, class是可以重復的并是子級的, 所以id僅使用在大的模塊上, class可用在重復使用率高及子級中;
4. class與id命名:命名要語義化,簡明化,盡量使用簡易的單詞組合; 避免使用中文拼音,以下是約定俗成的一些命名例子，請多加利用:
| 名稱 | Id | 名稱 | Id |
| 頁 眉 | header | 內 容 | content |
| 容 器 | container | 頁 腳 | footer |
| 版 權 | copyright | 導 航 | menu |
| 主導航 | mainMenu | 子導航 | subMenu |
| 標 志 | logo | 標 語 | banner |
| 標 題 | title | 側邊欄 | sidebar |
| 搜 索 | search | 按 鈕 | btn |
| 登 錄 | login | 鏈 接 | link |
常用類的命名應盡量以常見英文單詞為準，做到通俗易懂，并在適當的地方加以注釋。對于二級類/ID命名，則采用組合書寫的模式，后一個單詞的首字母應大寫：諸如“搜索框”則應命名為“searchInput”、“搜索圖標”命名這“searchIcon”、“搜索按鈕”命名為“searchBtn”。
5. css屬性書寫順序, 建議遵循 布局定位屬性-->自身屬性-->文本屬性-->其他屬性. 此條可根據自身習慣書寫, 但盡量保證同類屬性寫在一起. 屬性列舉: 布局定位屬性主要包括: margin ＆ padding ＆ float（包括clear） ＆ position（相應的 top,right,bottom,left） ＆ display ＆ visibility ＆ overflow等； 自身屬性主要包括: width & height & background & border; 文本屬性主要包括： font ＆ color ＆ text-align ＆ text-decoration ＆ text-indent等；其他屬性包括: list-style(列表樣式) ＆ vertical-vlign ＆ cursor ＆ z-index(層疊順序) ＆ zoom等. 我所列出的這些屬性只是最常用到的, 并不代表全部;
6. 書寫代碼前, 考慮并提高樣式重復使用率;
7. 充分利用html自身屬性及樣式繼承原理減少代碼量, 比如:
<ul class="list"><li>這兒是標題列表<span>2010-09-15</span></ul>
定義
ul.list li{position:relative} ul.list li span{position:absolute; right:0}
即可實現日期居右顯示.
8. 必須為大區塊樣式添加注釋, 小區塊適量注釋;
9. 代碼縮進與格式: 建議單行書寫;
第五部分：JS文件書寫規范
1. 文件編碼統一為utf-8, 書寫過程過, 每行代碼結束必須有分號; 原則上所有功能均根據XXX項目需求原生開發, 以避免網上down直接宕下來的代碼造成的代碼污染;
2. 庫引入: 原則上僅引入prototype庫, 若需引入第三方庫, 須與團隊其他人員討論決定;
3. 變量命名: 駝峰式命名. 原生JavaScript變量要求是純英文字母, 首字母須小寫, 如counter;另, 要求變量集中聲明, 避免全局變量.
4. 類命名: 首字母大寫, 駝峰式命名. 如 Counter;
5. 函數命名: 首字母小寫駝峰式命名. 如add(count);
6. 命名語義化, 盡可能利用英文單詞或其縮寫;
7. 后期優化中, JavaScript非注釋類中文字符須轉換成unicode編碼使用, 以避免編碼錯誤時亂碼顯示;
8. 代碼結構明了, 加適量注釋. 提高函數重用率;
第六部分：注釋規范
1. html注釋: 注釋格式 <!--這兒是注釋-->, '--'只能在注釋的始末位置,不可置入注釋文字區域;
2. css注釋: 注釋格式 /*這兒是注釋*/;
3. JavaScript注釋, 單行注釋使用'//這兒是單行注釋' ,多行注釋使用 /* 這兒有多行注釋 */;示例：
/*****************************************************
* 將數組arr轉化成為tableDatas
* 此舉是為了更方便解析數據
* 何楊，2012年2月7日14:03:43
*****************************************************/
function getTableDatasFromArr(arr){
var tableDatas=new Array();
// 遍歷這個數組
for(var i=0;i<arr.length;i++){
var node=arr[i];
var arr2=new Array();
for(var j=0;j<node.childNodes.length;j++){
var child=node.childNodes.item(j);
arr2.push(child.childNodes[0].nodeValue);
}
// 向表格中添加行
tableDatas.push(arr2);
}
return tableDatas;
}