前端编码规范

黄金定律

永远遵循同一套编码规范 -- 可以是这里列出的，也可以是你自己总结的。如果你发现本规范中有任何错误，敬请指正。通过 open an issue 为本规范添加或贡献内容。

不管有多少人共同参与同一项目，一定要确保每一行代码都像是同一个人编写的。

项目命名

项目名全部采用小写方式，以中划线分隔。比如： my-project-name

目录名

目录名参照上一条规则,有复数结构时，要采用复数命名法，比如说： scripts, styles, images, data-models

JavaScript 文件命名

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

CSS，SCSS 文件命名

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

HTML 文件命名

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

语法

用两个空格来代替制表符（tab） -- 这是唯一能保证在所有环境下获得一致展现的方法。
嵌套元素应当缩进一次（即两个空格）。
对于属性的定义，确保全部使用双引号，绝不要使用单引号。
不要在自闭合（self-closing）元素的尾部添加斜线 -- HTML5 规范中明确说明这是可选的。
不要省略可选的结束标签（closing tag）（例如，</li> 和 </body>）。

<!DOCTYPE html>
<html>
  <head>
    <title>Page title</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

HTML5 doctype

为每个 HTML 页面的第一行添加标准模式（standard mode）的声明，这样能够确保在每个浏览器中拥有一致的展现。

<!DOCTYPE html>
<html>
  <head>
  </head>
</html>

语言属性

根据 HTML5 规范：

强烈建议为 html 根元素指定 lang 属性，从而为文档设置正确的语言。这将有助于语音合成工具确定其所应该采用的发音，有助于翻译工具确定其翻译时所应遵守的规则等等。

更多关于 lang 属性的知识可以从此规范中了解。

这里列出了语言代码表。

以上只是给出了语言代码的大类，比如说中文就只给出了ZH，但是没有区分香港，台湾，大陆等。而微软给出的一份细分了zh-cn,zh-hk,zh-tw, Head to Microsoft for a detail list of language codes.

知乎贴：网页头部的声明应该是用 lang="zh" 还是 lang="zh-cn"？

但考虑到兼容性，目前需要指定中文的网页都统一用 zh-CN

<html lang="en-us">
  <!-- ... -->
</html>

IE compatibility mode

IE 支持通过特定的 <meta> 标签来确定绘制当前页面所应该采用的 IE 版本。除非有强烈的特殊需求，否则最好是设置为 edge mode，从而通知 IE 采用其所支持的最新的模式。

阅读这篇 stack overflow 上的文章可以获得更多有用的信息。

不同 doctype 在不同浏览器下的不同渲染模式，诡异模式总结的很到位.

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

字符编码

通过明确声明字符编码，能够确保浏览器快速并容易的判断页面内容的渲染方式。这样做的好处是，可以避免在 HTML 中使用字符实体标记（character entity，比如 “&” 的 HTML 字符实体是：&），从而全部与文档编码一致（一般采用 UTF-8 编码）。

<head>
  <meta charset="UTF-8">
</head>

引入 CSS 和 JavaScript

根据 HTML5 规范, 通常在引入 CSS 和 JavaScript 时不需要指明 type，因为 text/css 和 text/javascript 分别是他们的默认值。

HTML5 规范链接

<!-- External CSS -->
<link rel="stylesheet" href="code-guide.css">

<!-- In-document CSS -->
<style>
  /* ... */
</style>

<!-- JavaScript -->
<script src="code-guide.js"></script>

实用高于完美

尽量遵循 HTML 标准和语义，但是不应该以浪费实用性作为代价。任何时候都要用尽量小的复杂度和尽量少的标签来解决问题。

属性顺序

HTML 属性应该按照特定的顺序出现以保证易读性。

class
id
name
data-*
src, for, type, href, value , max-length, max, min, pattern
placeholder, title, alt
aria-*, role
required, readonly, disabled

Classes 是为高可复用组件设计的，理论上他们应处在第一位。Ids 更加具体而且应该尽量少使用（例如, 页内书签），所以他们处在第二位。

<a class="..." id="..." data-toggle="modal" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

Boolean 属性

Boolean 属性指不需要声明取值的属性。XHTML 需要每个属性声明取值，但是 HTML5 并不需要。

了解更多内容，参考 WhatWG section on boolean attributes:

一个元素中 Boolean 属性的存在表示取值 true，不存在则表示取值 false。

如果你必须为属性添加并不需要的取值，参照 WhatWG 的指引:

如果属性存在，他的取值必须是空字符串或者 [...] 属性的规范名称，不要在首尾包含空白字符。

简而言之，不要为 Boolean 属性赋值。

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

减少标签数量

在编写 HTML 代码时，需要尽量避免多余的父节点。很多时候，需要通过迭代和重构来使 HTML 变得更少。参考下面的示例:

<!-- Not so great -->
<span class="avatar">
  <img src="...">
</span>

<!-- Better -->
<img class="avatar" src="...">

JavaScript 生成标签

在 JavaScript 文件中生成标签让内容变得更难查找，更难编辑，性能更差。应该尽量避免这种情况的出现。

语法

用两个空格来代替制表符（tab） -- 这是唯一能保证在所有环境下获得一致展现的方法。
使用组合选择器时，保持每个独立的选择器占用一行。
为了代码的易读性，在每个声明的左括号前增加一个空格。
声明块的右括号应该另起一行。
每条声明 : 后应该插入一个空格。
每条声明应该只占用一行来保证错误报告更加准确。
所有声明应该以分号结尾。虽然最后一条声明后的分号是可选的，但是如果没有它，你的代码会更容易出错。
逗号分隔的取值，都应该在逗号之后增加一个空格（例如，box-shadow）。
不要在颜色值 rgb() rgba() hsl() hsla()和 rect() 中增加空格，并且不要带有取值前面不必要的 0 (比如，使用 .5 替代 0.5)。这样利于从多个属性值（既加逗号也加空格）中区分多个颜色值（只加逗号，不加空格）。
十六进制值都应该使用小写字母，例如 #fff。因为小写字母有更多样的外形，在浏览文档时，他们能够更轻松的被区分开来。
尽量使用简写形式的十六进制值，例如使用 #fff 替代 #ffffff。
为选择器中的属性取值添加引号，例如 input[type="text"]。只有在某些情况下是可选的，但是，为了代码的一致性，建议都加上双引号。
避免为 0 值指定单位，比如使用 margin: 0; 而不是 margin: 0px;。

对这里提到的规则有问题吗？参考 Wikipedia 中的 CSS 语法部分。

/* Bad CSS */
.selector, .selector-secondary, .selector[type=text] {
  padding:15px;
  margin:0px 0px 15px;
  background-color:rgba(0, 0, 0, 0.5);
  box-shadow:0px 1px 2px #CCC,inset 0 1px 0 #FFFFFF
}

/* Good CSS */
.selector,
.selector-secondary,
.selector[type="text"] {
  padding: 15px;
  margin-bottom: 15px;
  background-color: rgba(0,0,0,.5);
  box-shadow: 0 1px 2px #ccc, inset 0 1px 0 #fff;
}

声明顺序

相关的属性声明应当归为一组，并按照下面的顺序排列：

Positioning
Box model 盒模型
Typographic 排版
Visual 外观

Positioning 处在第一位，因为他可以使一个元素脱离正常文本流，并且能覆盖盒模型相关的样式。盒模型紧跟其后，因为它决定了组件的尺寸和位置。

其它属性只影响组件的内部或者不会对前面两种情况的结果产生影响，所以他们排在后面。

关于完整的属性以及他们的顺序，请参考 Recess。

.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;
}

不要使用 `@import`

与 <link> 标签相比，@import 指令要慢很多，不光增加了额外的请求次数，还会导致不可预料的问题。替代办法有以下几种：

使用多个 <link> 元素
通过 Sass 或 Less 类似的 CSS 预处理器将多个 CSS 文件编译为一个文件
通过 Rails、Jekyll 或其他系统中提供过 CSS 文件合并功能

请参考 Steve Souders 的文章了解更多知识。

<!-- Use link elements -->
<link rel="stylesheet" href="core.css">

<!-- Avoid @imports -->
<style>
  @import url("more.css");
</style>

媒体查询位置

尽量将媒体查询的位置靠近他们相关的规则。不要将他们一起放到一个独立的样式文件中，或者丢在文档的最底部。这样做只会让大家以后更容易忘记他们。这里是一个典型的案例。

.element { ... }
.element-avatar { ... }
.element-selected { ... }

@media (min-width: 480px) {
  .element { ...}
  .element-avatar { ... }
  .element-selected { ... }
}

带前缀属性

当使用特定厂商的带有前缀的属性时，通过缩进的方式，让每个属性的值在垂直方向对齐，这样便于多行编辑。

通常都是利用编辑工具的额外插件来做这件事的，比如 Sublime Text 的 Autoprefixer。当然，更加建议的是用 gulp 的 gulp-autoprefixer 插件来做更加自动化的编译。

/* Prefixed properties */
.selector {
  -webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
          box-shadow: 0 1px 2px rgba(0,0,0,.15);
}

单条声明的声明块

对于只包含一条声明的样式，为了易读性和便于快速编辑，建议将语句放在同一行。对于带有多条声明的样式，还是应当将声明分为多行。

这样做的关键因素是为了错误检测 -- 例如，CSS 校验器指出在 183 行有语法错误。如果是单行单条声明，你就不会忽略这个错误；如果是单行多条声明的话，你就要仔细分析避免漏掉错误了。

/* Single declarations on one line */
.span1 { width: 60px; }
.span2 { width: 140px; }
.span3 { width: 220px; }

/* Multiple declarations, one per line */
.sprite {
  display: inline-block;
  width: 16px;
  height: 15px;
  background-image: url(../img/sprite.png);
}
.icon           { background-position: 0 0; }
.icon-home      { background-position: 0 -20px; }
.icon-account   { background-position: 0 -40px; }

属性简写

坚持限制属性取值简写的使用，属性简写需要你必须显式设置所有取值。常见的属性简写滥用包括:

padding
margin
font
background
border
border-radius

大部分情况下，我们不需要为简写形式的属性声明指定所有值。例如，HTML 的 heading 元素只需要设置上、下边距（margin）的值，因此，在必要的时候，只需覆盖这两个值就可以。过度使用简写形式的属性声明会导致代码混乱，并且会对属性值带来不必要的覆盖从而引起意外的副作用。

MDN（Mozilla Developer Network）上一片非常好的关于 shorthand properties 的文章，对于不太熟悉简写属性声明及其行为的用户很有用。

/* 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;
}

Less 和 Sass 中的嵌套

避免不必要的嵌套。可以进行嵌套，不意味着你应该这样做。只有在需要给父元素增加样式并且同时存在多个子元素时才需要考虑嵌套。

// Without nesting
.table > thead > tr > th { … }
.table > thead > tr > td { … }

// With nesting
.table > thead > tr {
  > th { … }
  > td { … }
}

代码注释

代码是由人编写并维护的。请确保你的代码能够自描述、注释良好并且易于他人理解。好的代码注释能够传达上下文关系和代码目的。不要简单地重申组件或 class 名称。

对于较长的注释，务必书写完整的句子；对于一般性注解，可以书写简洁的短语。

/* Bad example */
/* Modal header */
.modal-header {
  ...
}

/* Good example */
/* Wrapping element for .modal-title and .modal-close */
.modal-header {
  ...
}

Class 命名

class 名称中只能出现小写字符和破折号（dashe）（不是下划线，也不是驼峰命名法）。破折号应当用于相关 class 的命名（类似于命名空间）（例如，.btn 和 .btn-danger）。
避免过度任意的简写。.btn 可以代表 button，但是 .s 不能表达任何意思。
Class 的命名应该尽量短，也要尽量明确。
使用有意义的名称。使用有组织的或目的明确的名称，不要使用表现形式（presentational）的名称。
基于最近的父 class 或基本（base）class 作为新 class 的前缀。
使用 .js-* class 来表示行为(相对于样式)，但是不要在 CSS 中包含这些 class。

在为 Sass 和 Less 变量命名是也可以参考上面列出的各项规范。

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

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

选择器

对于通用元素使用 class 而不是 tag 选择器，这样利于渲染性能的优化。
避免在经常出现的组件中使用一些属性选择器 (例如，[class^="..."])。浏览器性能会受到这些情况的影响。
减少选择器的长度，每个组合选择器选择器的条目应该尽量控制在 3 个以内。
只有在必要的时候才将 class 限制在最近的父元素内（也就是后代选择器）（例如，不使用带前缀的 class 时 -- 前缀类似于命名空间）。

扩展阅读:

/* Bad example */
span { ... }
.page-container #stream .stream-item .tweet .tweet-header .username { ... }
.avatar { ... }

/* Good example */
.avatar { ... }
.tweet-header .username { ... }
.tweet .avatar { ... }

代码组织

以组件为单位组织代码。
制定一个一致的注释层级结构。
使用一致的空白来分割代码块，这样做在查看大的文档时更有优势。
当使用多个 CSS 文件时，通过组件而不是页面来区分他们。页面会被重新排列，而组件移动就可以了。

/*
 * Component section heading
 */

.element { ... }


/*
 * Component section heading
 *
 * Sometimes you need to include optional context for the entire component. Do that up here if it's important enough.
 */

.element { ... }

/* Contextual sub-component or modifer */
.element-heading { ... }

缩进、分号、单行长度

缩进一律使用两个空格。
continuation-indentation 同样适用亮个空格，跟上一行对齐。
Statement 之后一律以分号结束，不可以省略。
单行长度，理论上不要超过80列，不过如果编辑器开启 soft wrap 的话可以不考虑单行长度。
接上一条，如果需要换行，存在操作符的情况，一定在操作符后换行，然后换的行缩进两个空格。
这里要注意，如果是多次换行的话就没有必要继续缩进了，比如说右边第二段这种就是最佳格式。

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

空行

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

变量命名

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

var thisIsMyName;

var goodID;

var AndroidVersion;

var iOSVersion;

var MAX_COUNT = 10;

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

字符常量

一般情况下统一使用 '' 单引号

null 的使用场景

To initialize a variable that may later be assigned an object value
To compare against an initialized variable that may or may not have an object value
To pass into a function where an object is expected
To return from a function where an object is expected

不适合 null 的使用场景

Do not use null to test whether an argument was supplied
Do not test an uninitialized variable for the value null

undefined 使用场景

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

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

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

对象字面量

// Bad
var team = new Team();
team.title = 'CrhFIT';
team.count = 25;

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

数组字面量

// 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];

单行注释

双斜线后，必须跟注释内容保留一个空格。
可独占一行, 前边不许有空行, 缩进与下一行代码保持一致。
可位于一个代码行的末尾，注意这里的格式。

// Good
if (condition) {

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

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

多行注释格式

最少三行, 格式如右。
前边留空一行。

何时使用？

难于理解的代码段。
可能存在错误的代码段。
浏览器特殊的 HACK 代码。
想吐槽的产品逻辑, 合作同事。
业务逻辑强相关的代码。

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

文档注释

各类标签 @param @method 等参考 http://usejsdoc.org/。
格式如右。

用在哪里？

All methods
All constructors
All objects with documented methods

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

括号对齐

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

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

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

if else else 前后留有空格

if (condition) {
  doSomething();
} else {
  doSomethingElse();
}

switch

采用右边的格式， switch 和括号之间有空格，case 需要缩进，break之后跟下一个 case 中间留一个空行。
花括号必须要，即使内容只有一行。
如右侧第二种情况，switch 的 falling through 一定要有注释特别说明，no default 的情况也需要注释特别说明况。

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

  case "third":
    // code
    break;

  default:
    // code
  }

switch (condition) {

  // obvious fall through
  case "first":
  case "second":
    // code
    break;

  case "third":
    // code

  /* falls through */
  default:
  // code
}

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

  case "second":
    // code
    break;

  // no default
}

for

普通 for 循环, 分号后留有一个空格，判断条件等内的操作符两边不留空格，前置条件如果有多个，逗号后留一个空格。
for-in 最好都要有 hasOwnProperty 的判断。

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

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

var prop;

for (prop in object) {
  if (object.hasOwnProperty(prop)) {
    console.log('Property name is ' + prop);
    console.log('Property value is ' + object[prop]);
  }
}

变量声明

所有函数内变量声明放在函数内头部，每个声明都用 var 且占一行。
严禁没有变量声明 var 直接做变量赋值，这会隐式地产生全局变量造成隐患。

function doSomethingWithItems(items) {

  var value = 10;
  var result = value + 10;

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

函数声明

一般建议先写逻辑后写声明定义，不过最好是将执行和定义分离到不同的文件当中去，有点类似 C 语言当中的 .h (头文件) 与 .m (执行文件)。
函数表达式与函数声明不同，函数表达式的（）前后必须有空格，而函数声明在有函数名的时候不需要空格，没有函数名的时候需要空格。
函数调用括号前后不需要空格。

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"
  };
}());

杂项

完全避免 == != 的使用，用严格比较条件 === !==。
eval 在非特殊情况下避免使用。
with 在非特殊情况下避免使用。

编辑器配置

根据以下的设置来配置你的编辑器，来避免常见的代码不一致和丑陋的 diffs。

用两个空格代替制表符（soft-tab 即用空格代表 tab 符）。
在保存时删除尾部的空白字符。为什么这么做？
设置文件编码为 UTF-8。
在文件结尾添加一个空白行。为什么这么做？

参照文档，将这些设置应用到项目的 .editorconfig 文件。例如，Bootstrap 中的 .editorconfig 文件。通过关于 EditorConfig 了解更多内容。

目录

Naming Project

HTML

CSS

JavaScript