##文档目录
##目录结构
-
引入亚信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。
/* Bad example */ .t { ... } .red { ... } .header { ... } /* Good example */ .tweet { ... } .important { ... } .tweet-header { ... }
####JavaScript 变量命名
-
标准变量采用驼峰标识
-
使用的ID的地方一定全大写
-
使用的URL的地方一定全大写, 比如说 reportURL
-
涉及Android的，一律大写第一个字母
-
涉及iOS的，一律小写第一个，大写后两个字母
-
常量采用大写字母，下划线连接的方式
-
构造函数，大写第一个字母
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> -
语言种类，默认声明文档使用中文
<html lang="zh-cn"> <!-- ... --> </html> -
页面编码，必须申明文档的charset编码，且与文件本身编码保持一致，推荐使用utf-8编码
<head> <meta http-equiv="content-type" content="text/html;charset=utf-8"/> </head> -
IE兼容模式，默认使用最高浏览器的渲染模式，考虑向后兼容
<meta http-equiv="X-UA-Compatible" content="IE=Edge"> -
样式和脚本，引入 CSS 和 JavaScript 时不需要指明 type
<!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标签名、属性和值全部小写，属性不能为空且必须加双引号
- 不要使用
 进行缩进 - 不要使用行内样式
- 不要在内联元素中嵌入块级元素
- 不要在自动闭合标签结尾处使用斜线
<img src="photo.png" alt="头像">
- 不要在
Boolean属性值中声明取值的属性<input type="text" disabled>
- HTML 属性应该按照特定的顺序出现以保证易读性
-
id -
class -
name -
data-* -
src,for,type,href -
title,alt<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编码
@charset "utf-8"; -
样式表中的中文字体使用unicode转码
font-family: Tahoma, "\5fae\8f6f\96c5\9ed1", "\5B8B\4F53"; -
使用clearfix或overflow清除子元素的浮动，而不是空标签
.clearfix:after{ visibility:hidden; display:block; font-size:0; content:" "; clear:both; height:0; } .clearfix{ zoom:1; } -
针对某个浏览器写的样式或某个浏览器BUG的样式，必须加上注释说明
.clearfix{ zoom:1; /* for IE6 IE7 */ } -
不使用影响页面性能expression表达式与filter，实现必要的特殊效果时，允许使用
/* expression */ .class{width:expression(this.width>100?'100px':'auto');} /* filter */ .class{filter:alpha(opacity=50);}
####书写格式
-
使用四个空格的TAB键来进行代码缩，保证代码在各种环境下显示一致
-
为了代码的易读性，在每个声明的左括号前增加一个空格。
-
声明块的右括号应该另起一行
-
选择器、属性和值都使用小写，并且为选择器中的属性取值添加引号
input[type="text"] -
使用组合选择器时，保持每个独立的选择器占用一行
-
使用逗号分隔的取值，都应该在逗号之后增加一个空格。比如说
box-shadow -
最后一个属性值也以分号结尾，避免后期对维护带来的麻烦
.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），方便以后增加或修改.ui-box1 { z-index: 50; } .ui-box2 { z-index: 55; } -
省略url引用中的引号，其他需要引号的地方使用双引号
.ui-box { background:url(bg.png); } .ui-box:after { content:"."; } -
先写带有浏览器私有标志的，并且通过缩进使取值垂直对齐以便多行编辑。
.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/* 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 混杂
.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; }
-
####代码组织
-
以模块为单位组织代码，使用继承以及提取公共样式，提高代码复用率
<!-- 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前后留有空格
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 的地方都必须使用花括号
// Good if (condition) { doSomething(); } // Bad if (condition) doSomething(); doSomethingElse();
####变量声明
-
所有函数内的变量声明应该放在函数内头部，只使用一个 var(多了JSLint报错)， 一个变量一行， 在行末跟注释
-
优先使用单引号（'）而不是双引号（"）表示字符常量
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 均会报错
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" 对变量进行判断
// Bad var person; console.log(person === undefined); //true // Good console.log(typeof person); // "undefined"
####Object对象
// Bad
var team = new Team();
team.title = "AlloyTeam";
team.count = 25;
// Good semi colon 采用 Followed by space 的形式
var team = {
title: "AlloyTeam",
count: 25
};
####Array数组
// 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;
switch (condition) { case "first": // code break; case "third": // code break; default: // code }
####for
-
普通for循环, 分号后留有一个空格， 判断条件等内的操作符两边不留空格
-
前置条件如果有多个，逗号后留一个空格
-
for-in 一定要有 hasOwnProperty 的判断， 否则 JSLint 或者 JSHint 都会有一个 warn
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标签保持格式统一
<!-- 头部 --> <div class="header"> <!-- 导航 --> <ul class="nav"> <li><a href="#">nav1</a></li> <li><a href="#">nav2</a></li> </ul> <!-- /导航 --> </div> <!-- /头部 --> -
代码本身的注释方法，单行代码的注释也保持在同行，两端空格；多行代码的注释起始和结尾都另起一行并左缩进对齐
<!-- <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 注释
-
单行注释，写在被注释对象的上一行，对属性及值的注释写于分号后
/* 单行注释文字 */ .ui-box { border: 1px solid #ccc; } .ui-box-head{ height:20px; line-height:20px;/* 这里是对line-height的一个注释 */ overflow:hidden; } -
块状注释，用于布局结构或模块，注释保持统一的缩进对齐，前面留空一行
/* * 块状注释文字 * 块状注释文字 */ .ui-box {} .ui-box-head {} .ui-box-head .ui-box-head-title{} .ui-box-container{}
####JavaScript 注释
-
单行注释
-
双斜线后，必须跟注释内容保留一个空格；
-
可独占一行, 前边不许有空行, 缩进与下一行代码保持一致；
-
位于一个代码行的末尾，双斜线距离分号四个空格，双斜线后始终保留一个空格
// Good if (condition) { // if you made it here, then all security checks passed allowed(); } var zhangsan = "zhangsan"; // 双斜线距离分号四个空格，双斜线后始终保留一个空格
-
-
块状注释
-
注释代码最少三行，保持统一的缩进，前面留空一行
-
用于难于理解或者存在错误的代码段，也适用于HACK代码和逻辑较强的代码注释
/* * 注释内容与星标前保留一个空格 */
-
####JsDoc 注释
-
JsDoc 是一个根据注释规范自动生成文档的工具
-
详细的文档规范可参考 usejsdoc.org
/** * here boy, look here , here is girl * @method lookGril * @param {Object} balabalabala * @return {Object} balabalabala */
####UPDATE
- 2014-08-20
- 细化HTML,CSS范内容目录，和JavaScript保持一致
- 引入代码格式化和校验工具
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent