团队编码规范

#团队编码规范

##文档目录

##命名规范

####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

####基础设施

文档声明，文件应以“<!DOCTYPE ……>”首行顶格开始，推荐使用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标签名、属性和值全部小写，属性不能为空且必须加双引号
不要使用&nbsp进行缩进
不要使用行内样式
不要在内联元素中嵌入块级元素
不要在自动闭合标签结尾处使用斜线
- <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>
<!-- /头部 -->

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


```
注释在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
 */