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. 书写链接地址时, 必须避免重定向，例如：href="http://www.baidu.com/", 即须在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;
}