团队规范文档

目录结构

引入亚信UED的基础前端框架，包括JS底层库，UI样式库，开发规范，自动化工具，团队知识库
引入cmd,seajs,nodejs,grunt,npm,markdown等

细化各级目录分类，方便清晰管理，考虑文件的部署压缩合并

  my-project-name
  │
  ├── res
  │   ├── conf	// ajax数据接口，seajs配置，Grunt配置，npm包管理
  │   ├── ai
  │   │  ├── aijs		// JS库，包含基础扩展以及工具方法
  │   │  ├── aiui		// UI库，包含样式模块以及交互组件
  │   │  ├── aicg		// 编码规范[MD]，包含各种书写规范以及校验工具
  │   │  ├── aimd		// 知识库[MD]，包含新人成长，以及常见疑难问题解决方案
  │   │  └── aiat		// 工具库[MD]，包含前端开发以及自动化部署工具
  │   ├── scripts
  │   │  ├── lib		// 基础框架 jQuery, Zepto, Handlebars, extjs
  │   │  ├── fn 		// 功能库 D3.js, Map.js
  │   │  ├── ui 		// 插件库 zTree, omGrid, My97, artDialog, autocomplete, validform
  │   │  └── page 	
  │   │  	  ├── common	// 公用的模块
  │   │  	  ├── login		// 登录 		
  │   │  	  ├── search    // 搜索  	
  │   │  	  └── business  // 办理  
  │   ├── models 	
  │   │  ├── widget   // 插件模块
  │   │  │  └── collapse   
  │   │  │     ├── data   // 数据
  │   │  │     ├── tpl    // 模版		
  │   │  │     └── hbs    // 模版预编译
  │   │  │
  │   │  └── page
  │   │  	  ├── common	// 公用的模块
  │   │     │  ├── data   	
  │   │     │  ├── tpl    			
  │   │     │  └── hbs    		
  │   │  	  ├── login		// 登录 		
  │   │  	  └── search    // 搜索  
  │   ├── styles
  │   │  ├── globe		// 全局样式，Less生成主题文件
  │   │  │  ├── default
  │   │  │  │  └── globe.css   		// 默认主题
  │   │  │  ├── blue
  │   │  │  │  └── globe.blue.css   	// 蓝色主题		
  │   │  │  └── dark
  │   │  │     └── globe.dark.css   	// 黑色主题
  │   │  └── page			
  │   │  	  ├── login		
  │   │     │  └── login.css   // 登录页样式				
  │   │  	  └── search    
  │   │        └── search.css  // 搜索页样式
  │   │
  │   ├── page
  │   │  ├── search.html    // 搜索页面  	
  │   │  └── business
  │   │     ├── query.html    // 查询页面				
  │   │     └── pay.html      // 充值页面				
  │   │
  │   └── index.html
  │
  └── login.html

命名规范

CSS 类名

保持 Class 命名为全小写，可以使用短划线（不要使用下划线和 camelCase驼峰式命名）
短划线应该作为相关类的自然间断。(例如，.btn 和 .btn-danger)。
避免过度使用简写。.btn 可以很好地描述 button，但是 .s 不能代表任何元素。
Class 的命名应该尽量短，也要尽量明确。
使用有意义的名称；使用结构化或者作用目标相关，而不是抽象的名称。
命名时使用最近的父节点或者父 class 作为前缀
使用 .js-* classes 来表示行为(相对于样式)，但是不要在 CSS 中包含这些 classes。

1
2
3
4
5
6
7
8
9


		/* Bad example */
		.t { ... }
		.red { ... }
		.header { ... }

		/* Good example */
		.tweet { ... }
		.important { ... }
		.tweet-header { ... }

JavaScript 变量命名

标准变量采用驼峰标识
使用的ID的地方一定全大写
使用的URL的地方一定全大写, 比如说 reportURL
涉及Android的，一律大写第一个字母
涉及iOS的，一律小写第一个，大写后两个字母
常量采用大写字母，下划线连接的方式
构造函数，大写第一个字母

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


		var thisIsMyName;

		var goodID;

		var AndroidVersion;

		var iOSVersion;

		var MAX_COUNT = 10;

		function Person(name) {
		    this.name = name
		}

####HTML，TPL文件命名

多个单词组成时，采用中划线连接方式，比如说：error-report.html

####CSS，LESS文件命名

多个单词组成时，采用中划线连接方式，比如说: retina-sprites.scss

####JavaScript，JSON文件命名

多个单词组成时，采用中划线连接方式，比如说：账号模型文件 account-model.js

##HTML ####基础设施

文档声明，文件应以“”首行顶格开始，推荐使用html5文档类型
```
  <!DOCTYPE html>
  <html>
      <head>
      </head>
  </html>
```
语言种类，默认声明文档使用中文

1
2
3


		<html lang="zh-cn">
		    <!-- ... -->
		</html>

页面编码，必须申明文档的charset编码，且与文件本身编码保持一致，推荐使用utf-8编码

1
2
3


		<head>
		    <meta http-equiv="content-type" content="text/html;charset=utf-8"/>
		</head>

IE兼容模式，默认使用最高浏览器的渲染模式，考虑向后兼容

1

		<meta http-equiv="X-UA-Compatible" content="IE=Edge">

样式和脚本，引入 CSS 和 JavaScript 时不需要指明 type

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


		<!DOCTYPE html>
		<html lang="zh-cn">
			<head>
			    <meta http-equiv="content-type" content="text/html;charset=utf-8">
			    <title>HTML规范</title>
			    <link rel="stylesheet" href="style.css"/>
			    <style></style>
			</head>
			<body>
			    <script src="script.js"></script>
			</body>
		</html>

书写格式

代码保持简洁的树形结构，必须使用四个空格的TAB键来进行代码缩进
HTML标签名、属性和值全部小写，属性不能为空且必须加双引号
不要使用&nbsp进行缩进
不要使用行内样式
不要在内联元素中嵌入块级元素
不要在自动闭合标签结尾处使用斜线
- <img src="photo.png" alt="头像">
不要在Boolean属性值中声明取值的属性
- <input type="text" disabled>
HTML 属性应该按照特定的顺序出现以保证易读性
- id
- class
- name
- data-*
- src,for,type,href
- title, alt

1
2
3


			<a id="code_guide" class="code-guide" data-modal="toggle" href="#">Link</a>
			<input name="sex" class="form-control" type="text">
			<img src="photo.jpg" alt="头像">

语义优化

根据网页中某种类型的内容，使用特定HTML语义化的标签编写页面结构
对a元素提供title属性，img提供alt属性，加强"资源型"内容的可访问性
当空标签使用背景图时，必须加上相对应的文字说明，并按需隐藏文字，加强"不可见"内容的可访问性
使用div代替table进行布局，但是表现具有明显表格的数据，table还是首选
实用高于完美，尽量的遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价

CSS

基础设施

CSS文件顶格位置申明文档的编码charset，推荐使用UTF-8编码

1

		@charset "utf-8";

样式表中的中文字体使用unicode转码

  font-family: Tahoma, "\5fae\8f6f\96c5\9ed1", "\5B8B\4F53";

使用clearfix或overflow清除子元素的浮动，而不是空标签

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


		.clearfix:after{
		    visibility:hidden;
		    display:block;
		    font-size:0;
		    content:" ";
		    clear:both;
		    height:0;
		}
		.clearfix{
		    zoom:1;
		}

针对某个浏览器写的样式或某个浏览器BUG的样式，必须加上注释说明

1
2
3


		.clearfix{
		    zoom:1; /* for IE6 IE7 */
		}

不使用影响页面性能expression表达式与filter，实现必要的特殊效果时，允许使用

1
2
3
4
5


		/* expression */
		.class{width:expression(this.width>100?'100px':'auto');}

		/* filter */
		.class{filter:alpha(opacity=50);}

书写格式

使用四个空格的TAB键来进行代码缩，保证代码在各种环境下显示一致
为了代码的易读性，在每个声明的左括号前增加一个空格。
声明块的右括号应该另起一行
选择器、属性和值都使用小写，并且为选择器中的属性取值添加引号input[type="text"]
使用组合选择器时，保持每个独立的选择器占用一行
使用逗号分隔的取值，都应该在逗号之后增加一个空格。比如说box-shadow
最后一个属性值也以分号结尾，避免后期对维护带来的麻烦

1
2
3
4
5
6
7


		.selector,
		.selector-secondary,
		.selector[type="text"] {
		    padding: 15px;
		    margin-bottom: 15px;
		    box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
		}

所有的十六进制值都应该使用小写字母，并且使用缩写方式 color:#fff;
当值为0时省略单位 margin:0;
z-index一般以5为一个步长（如50,55,60），方便以后增加或修改

1
2
3
4
5
6


		.ui-box1 {
		    z-index: 50;
		}
		.ui-box2 {
		    z-index: 55;
		}

省略url引用中的引号，其他需要引号的地方使用双引号

1
2
3
4
5
6


		.ui-box {
		    background:url(bg.png);
		}
		.ui-box:after {
		    content:".";
		}

先写带有浏览器私有标志的，并且通过缩进使取值垂直对齐以便多行编辑。

1
2
3
4
5


		.ui-box {
		    -webkit-box-shadow:0 0 0 #000;
		       -moz-box-shadow:0 0 0 #000;
		            box-shadow:0 0 0 #000;
		}

不建议使用!important，不建议使用@import，
原则上不允许使用Hack，不兼容问题可以通过改变方法和思路来解决，对于浏览器自身的缺陷，可以允许使用适当的Hack
当使用属性简写时你必须设置所有取值，常见的属性滥用包括
- padding,margin,font,background,border,border-radius

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


			/* Bad example */
			.element {
			    margin: 0 0 10px;
			    background: red;
			    background: url("image.jpg");
			    border-radius: 3px 3px 0 0;
			}

			/* Good example */
			.element {
			    margin-bottom: 10px;
			    background-color: red;
			    background-image: url("image.jpg");
			    border-top-left-radius: 3px;
			    border-top-right-radius: 3px;
			}

根据属性的重要性按顺序书写
- Positioning 位置 > Box model 盒模型 > Typographic 排版 > Visual 外观 > Misc 混杂

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29


			.declaration-order {
			    /* Positioning 位置*/
			    position: absolute;
			    top: 0;
			    right: 0;
			    bottom: 0;
			    left: 0;
			    z-index: 100;

			    /* Box-model 盒模型*/
			    display: block;
			    float: right;
			    width: 100px;
			    height: 100px;

			    /* Typography 排版*/
			    font: normal 13px "Helvetica Neue", sans-serif;
			    line-height: 1.5;
			    color: #333;
			    text-align: center;

			    /* Visual 外观*/
			    background-color: #f5f5f5;
			    border: 1px solid #e5e5e5;
			    border-radius: 3px;

			    /* Misc 混杂*/
			    opacity: 1;
			}

代码组织

以模块为单位组织代码，使用继承以及提取公共样式，提高代码复用率

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


		<!-- ui-box:模块基类，用于定义模块的公共结构样式 -->
		<div class="ui-box">

		    <!-- ui-box-head:模块头部 -->
		    <div class="ui-box-head">
		        <h3 class="ui-box-head-title">标题</h3>
		    </div>

		    <!-- ui-box-container:模块内容 -->
		    <div class="ui-box-container">
		        <div class="ui-box-content">内容</div>
		    </div>
		</div>

JavaScript

缩进,分号,换行,空格

4个空格保持代码缩进
在语句末尾使用分号结束，清楚语句的起止位置
多于120个字符应换行，优先在左花括号后、操作符后进行换行；
if else前后留有空格

1
2
3
4
5
6
7


		if (typeof state === "undefined" ||
		    typeof state.cdnrejected === "undefined" ||
		    state.cdnrejected !== true) {
		    url = "http://pub.state.com/qqfind/js/location4.js";
		} else {
		    url = "http://find.state.com/js/location4.js";
		}

空行

方法之间加
单行或多行注释前加
逻辑块之间加空行增加可读性

括号对齐

括号前后有空格，花括号起始不另换行，结尾新起一行
花括号必须要，即使内容只有一行，决不允许右边第二种情况
涉及 if for while do…while try…catch…finally 的地方都必须使用花括号

1
2
3
4
5
6
7
8
9


		// Good
		if (condition) {
		    doSomething();
		}

		// Bad
		if (condition)
		    doSomething();
		    doSomethingElse();

####变量声明

所有函数内的变量声明应该放在函数内头部，只使用一个 var(多了JSLint报错)，一个变量一行，在行末跟注释
优先使用单引号（'）而不是双引号（"）表示字符常量

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


		function doSomethingWithItems(items) {

		    var value = 10,    // 注释
		        result = value + 10,    // 注释
		        name = 'rose',	 // 注释
		        i,    // 注释
		        len;    // 注释

		    for (i=0, len=items.length; i < len; i++) {
		        doSomething(items[i]);
		    }
		}

####函数声明

函数声明和函数表达式的不同，函数表达式的（）前后必须有空格，而函数生命在有函数名的时候不需要空格，没有函数名的时候需要空格。
函数调用括号前后不需要空格
立即执行函数的写法, 最外层必须包一层括号
“use strict” 决不允许全局使用，必须放在函数的第一行，可以用自执行函数包含大的代码段, 如果 “use strict” 在函数外使用， JSLint 和 JSHint 均会报错

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


		function doSomething(item) {
	    	// do something
		}

		var doSomething = function (item) {
		    // do something
		}


		// Good
		doSomething(item);

		// Bad: Looks like a block statement
		doSomething (item);


		// Good
		var value = (function() {

		    // function body
		    return {
		        message: "Hi"
		    }
		}());


		// Good
		(function() {
		    "use strict";

		    function doSomething() {
		        // code
		    }

		    function doSomethingElse() {
		        // code
		    }

		})();

####undefined使用

永远不要直接使用undefined进行变量判断
使用字符串 “undefined” 对变量进行判断

1
2
3
4
5
6


		// Bad
		var person;
		console.log(person === undefined);    //true

		// Good
		console.log(typeof person);    // "undefined"

####Object对象

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


	// Bad
	var team = new Team();
	team.title = "AlloyTeam";
	team.count = 25;

	// Good  semi colon 采用 Followed by space 的形式
	var team = {
	    title: "AlloyTeam",
	    count: 25
	};

####Array数组

1
2
3
4
5
6
7
8


	// Bad
	var colors = new Array("red", "green", "blue");
	var numbers = new Array(1, 2, 3, 4);


	// Good
	var colors = [ "red", "green", "blue" ];
	var numbers = [ 1, 2, 3, 4 ];

####switch

花括号必须要，即使内容只有一行;
switch和括号之间有空格， case需要缩进;
break之后跟下一个case中间留一个blank line;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


		switch (condition) {
		    case "first":
		        // code
		        break;

		    case "third":
		        // code
		        break;

		    default:
		    // code
		}

####for

普通for循环, 分号后留有一个空格，判断条件等内的操作符两边不留空格
前置条件如果有多个，逗号后留一个空格
for-in 一定要有 hasOwnProperty 的判断，否则 JSLint 或者 JSHint 都会有一个 warn

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


		var values = [ 1, 2, 3, 4, 5, 6, 7 ],
		    i, len;

		for (i=0, len=values.length; i<len; i++) {
		    process(values[i]);
		}



		var prop;
		for (prop in object) {

		    // 注意这里一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn ！
		    if (object.hasOwnProperty(prop)) {
		        console.log("Property name is " + prop);
		        console.log("Property value is " + object[prop]);
		    }
		}

其他

避免使用a==b, a!=b，推荐用严格比较条件 a===b, a!==b
非特殊业务，禁用eval,with

##注释规范 ####HTML 注释

代码说明的注释方法，采用标签闭合的写法，与HTML标签保持格式统一

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


		<!-- 头部 -->
		<div class="header">
		    <!-- 导航 -->
		    <ul class="nav">
		        <li><a href="#">nav1</a></li>
		        <li><a href="#">nav2</a></li>
		    </ul>
		    <!-- /导航 -->
		</div>
		<!-- /头部 -->

代码本身的注释方法，单行代码的注释也保持在同行，两端空格；多行代码的注释起始和结尾都另起一行并左缩进对齐

1
2
3
4
5
6
7


		<!-- <h1 class="header"><a href="#">LOGO</a></h1> -->
		<!--
		<ul class="nav">
		    <li><a href="#">nav1</a></li>
		    <li><a href="#">nav2</a></li>
		</ul>
		-->

注释在IE6中的BUG
- 如果两个浮动元素之间存在注释，那么可能导致布局错位或文字的BUG
- 通常这种情况，把注释去掉是最好的解决方案

####CSS 注释

单行注释，写在被注释对象的上一行，对属性及值的注释写于分号后

1
2
3
4
5
6
7
8
9


		/* 单行注释文字 */
		.ui-box {
		    border: 1px solid #ccc;
		}
		.ui-box-head{
		    height:20px;
		    line-height:20px;/* 这里是对line-height的一个注释 */
		    overflow:hidden;
		}

块状注释，用于布局结构或模块，注释保持统一的缩进对齐，前面留空一行

1
2
3
4
5
6
7
8


		/*
		 * 块状注释文字
		 * 块状注释文字
		 */
		.ui-box {}
		.ui-box-head {}
		.ui-box-head .ui-box-head-title{}
		.ui-box-container{}

####JavaScript 注释

单行注释
- 双斜线后，必须跟注释内容保留一个空格；
- 可独占一行, 前边不许有空行, 缩进与下一行代码保持一致；
- 位于一个代码行的末尾，双斜线距离分号四个空格，双斜线后始终保留一个空格

1
2
3
4
5
6
7
8


			// Good
			if (condition) {

			    // if you made it here, then all security checks passed
			    allowed();
			}

			var zhangsan = "zhangsan";    // 双斜线距离分号四个空格，双斜线后始终保留一个空格

块状注释
- 注释代码最少三行，保持统一的缩进，前面留空一行
- 用于难于理解或者存在错误的代码段，也适用于HACK代码和逻辑较强的代码注释

1
2
3


			/*
			 * 注释内容与星标前保留一个空格
			 */

####JsDoc 注释

JsDoc 是一个根据注释规范自动生成文档的工具
详细的文档规范可参考 usejsdoc.org

1
2
3
4
5
6


		/**
		 * here boy, look here , here is girl
		 * @method lookGril
		 * @param {Object} balabalabala
		 * @return {Object} balabalabala
		 */

####UPDATE

2014-08-20
- 细化HTML,CSS范内容目录，和JavaScript保持一致
- 引入代码格式化和校验工具

文章目录

目录结构

命名规范

CSS 类名

JavaScript 变量命名

书写格式

语义优化

CSS

基础设施

书写格式

代码组织

JavaScript

缩进,分号,换行,空格

空行

括号对齐

其他