制定自己团队的前端开发规范

篇幅可能会比较长，但是我感觉有一套规范对于一个团队其实还是很重要的，这样在维护起来也会很方便，如果接下来的规范感觉对你们团队有帮助，希望可以在团队中进行实践或者推荐给你的leader，代码规范参考自：腾讯alloyteam团队，希望大家可以跟着看一遍，各取所需。

后续的文章我也补充齐全了，一共有两篇，都是实战篇，一篇是制定自己团队的前端开发规范之 eslint，另外一篇是手摸手带你实践标准的前端开发规范，希望大家可以去看一下，然后把这套规范实践起来，让自己的开发存在更少的bug。

如果可以的话，实践过程中有用的不舒服的，麻烦给我进行反馈，这样才能知道这套规则适不适合大部分人去用，根据大家的意见，取其精华去其糟粕让这套规范变得更实用。

命名规范

项目命名

全部采用小写方式，以下划线分隔。例：my_project_name

目录命名

参照项目命名规则；

有复数结构时，要采用复数命名法。

例：scripts，styles，images，data_models

vue的项目中，components下的组件目录名，使用大驼峰命令

例：LeftBar

JS文件命名

参照项目命名规则。

例：account_model.js

CSS, SCSS文件命名

参照项目命名规则。

例：retina_sprites.css

HTML文件命名

参照项目命名规则。

例：error_log.html

HTML 规范

语法：

缩进使用 tab（2 个空格）；
嵌套的节点应该缩进；
在属性上，使用双引号，不要使用单引号；
属性名全小写，用中划线（-）做分隔符；
要在自动闭合标签结尾处使用斜线；

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

标准模式

在开头规定 doctype，来启动标准模式，doctype 要大写。

<!DOCTYPE html>
<html>
  ...
</html>

规定字符编码

通过声明一个明确的字符编码，让浏览器轻松、快速的确定适合网页内容的渲染方式，通常指定为'UTF-8'。

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
  </head>
  ...
</html>

IE 兼容模式

用 meta 标签指定页面应该使用什么版本的 IE 来渲染。

<!DOCTYPE html>
<html>
  <head>
    <meta http-equiv="X-UA-Compatible" content="IE=Edge" />
  </head>
  ...
</html>

减少标签数量

在编写 HTML 代码时，需要尽量避免多余的父节点；

<!-- bad -->
<span class="avatar">
  <img src="..." />
</span>

<!-- good -->
<img class="avatar" src="..." />

语义化标签

html 的标签能使用语义化的，尽量使用语义化标签，避免一个页面都是 div 或者 p 标签

<!-- bad -->
<div>
  <p></p>
</div>

<!-- good -->
<header></header>
<footer></footer>

CSS 规范

缩进

使用 tab 缩进（2 个空格）

.element {
  border-radius: 10px;
  width: 50px;
  height: 50px;
}

分号

每个声明结束都要加分号

.element {
  border-radius: 10px;
  width: 50px;
  height: 50px;
}

注释

注释统一使用 /* */

.element {
  /* border-radius: 10px; */
  width: 50px;
  height: 50px;
}

引号

url 的内容要用引号
属性选择器中的属性值需要引号

.element:after {
  content: "";
  background-image: url("logo.png");
}

li[data-type="single"] {
  ...;
}

命名

类名使用小写字母，以中划线分隔
id 采用驼峰式命名
scss 中的变量、函数、混合、placeholder 采用驼峰式命名

/* class */
.element-content {
  ...;
}

/* id */
#myDialog {
  ...;
}

/* 变量 */
$colorBlack: #000;

/* 混合 */
@mixin centerBlock {
  ...;
}

JavaScript 规范

缩进

使用 tab 缩进（2 个空格）

if (x < y) {
  x += 10;
} else {
  x += 1;
}

变量命名

标准变量采用驼峰式命名
'Android'在变量名中大写第一个字母
'iOS'在变量名中小写第一个，大写后两个字母
常量全大写，用下划线连接
构造函数，大写第一个字母
jquery 对象必须以'$'开头命名

var thisIsMyName;

var AndroidVersion;

var iOSVersion;

var MAX_COUNT = 10;

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

// not good
var body = $("body");

// good
var $body = $("body");

变量声明

一个函数作用域中所有的变量声明尽量提到函数首部。如果可以使用 let 和 const 的，要使用 let 和 const。

function doSomethingWithItems(items) {
  // use one var
  let value = 10,
    result = value + 10,
    i,
    len;

  for (i = 0, len = items.length; i < len; i++) {
    result += 10;
  }
}

单行长度

不要超过 100，但如果编辑器开启 word wrap 可以不考虑单行长度。

分号

统一要加分号。

空格

以下几种情况不用写空格：

对象的属性名后
函数调用括号前
无论是函数声明还是函数表达式，'('前不要空格
数组的'['后和']'前
运算符'('后和')'前

以下几种情况一定要写空格：

三元运算符'?:'前后
逗号后必须要有空格
代码块'{'前
下列关键字前：else, while, catch, finally
下列关键字后：if, else, for, while, do, switch, case, try,catch, finally, with, return, typeof
单行注释'//'后（若单行注释和代码同行，则'//'前也需要），多行注释'*'后
对象的属性值前
for 循环，分号后留有一个空格，前置条件如果有多个，逗号后留一个空格
无论是函数声明还是函数表达式，'{'前一定要有空格
函数的参数之间

这些后续会用 eslint 和 prettier 进行格式化

例：

// not good
var a = {
  b : 1
};

// good
var a = {
  b: 1
};

// not good
++x;
y++;
z = x ? 1:2;

// good
++x;
y++;
z = x ? 1 : 2;

// not good
var a = [ 1, 2 ];

// good
var a = [1, 2];

// good
var doSomething = function(a, b, c) {
  // do something
};

// good
doSomething(item);

// not good
for (let i = 0;i < 6;i++) {
  x++;
}

// good
for (let i = 0; i < 6; i++) {
  x++;
}

空行

以下几种情况一定要有空行

变量声明后（当变量声明在代码块的最后一行时，则无需空行）
注释前（当注释在代码块的第一行时，则无需空行）
文件最后保留一个空行

var x = 1;

// 注释前要有空行
if (x >= 1) {
  var y = x + 1;
}

换行

换行的地方，行末必须有','或者运算符；

以下几种情况不需要换行：

下列关键字后：else, catch, finally
代码块'{'前

以下几种情况需要换行：

代码块'{'后和'}'前
变量赋值后

// not good
var a = {
    b: 1
    , c: 2
};

x = y
    ? 1 : 2;

// good
var a = {
    b: 1,
    c: 2
};

x = y ? 1 : 2;

// good
if (condition) {
    ...
} else {
    ...
}

try {
    ...
} catch (e) {
    ...
} finally {
    ...
}

// not good
function test()
{
    ...
}

// good
function test() {
    ...
}

// not good
var a, foo = 7, b,
    c, bar = 8;

// good
var a,
    foo = 7,
    b, c, bar = 8;

注释

单行注释

注释单独一行的情况下，注释的//后面要跟一个空格
注释如果和代码同一行，代码分号结束后，要跟一个空格，注释的//后也要跟一个空格

例：

// 调用函数
foo();

var maxCount = 10; // 这是一个变量

多行注释

多行注释使用下面这种形式：

/**
 * 代码注释1
 * 代码注释2
 */

多行注释建议在以下几种情况使用：

难于理解的代码段
可能存在错误的代码段
浏览器特殊的 HACK 代码
业务逻辑强相关的代码

函数注释

复杂的函数，所有类，都必须进行函数注释，函数注释使用业界统一的规范，方便后续使用 jsdoc 生成文档。

例：

/**
 * 获取任务的名称
 * @param id {Number} 传入需要获取名称的人物id
 * @return {String} 返回的姓名
 * @author shi 2015/07/21 可以不写
 * @version 1.1.0 可以不写
 * @example 示例代码，可以不写
 */
function getTaskName(id) {
  let name = "test";
  return name;
}

引号

最外层统一使用单引号，除非字符串嵌套的情况。

// not good
var x = "test";

// good
var y = 'foo',
  z = '<div id="test"></div>';

对象，数组

对象属性名不需要加引号，如对象属性名是中划线命名的需要加引号（eslint 的 rules）
对象以缩进的形式书写，不要写在一行（单个属性可以写一行，es6 导入方法时可以使用单行）；
数组、对象最后不要有逗号。

// good
var a = {
  b: 1,
  c: 2
};

括号

下列关键字后必须有大括号（即使代码块的内容只有一行）：if, else, for, while, do, switch, try, catch, finally, with。

// not good
if (condition) doSomething();

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

undefined

永远不要直接使用 undefined 进行变量判断；

使用 typeof 和字符串'undefined'对变量进行判断。

// not good
if (person === undefined) {
    ...
}

// good
if (typeof person === 'undefined') {
    ...
}

不允许存在多层嵌套的条件判断和循环（最多三层）

条件判断能使用三目运算符和逻辑运算符解决的，就不要使用条件判断，但是谨记不要写太长的三目运算符。

例：

// bad
if (x === 10) {
  return 'valid';
} else {
  return 'invalid';
}

// good
return x === 10 ? 'valid' : 'invalid';

// bad
if (!x) {
  if (!y) {
    x = 1;
  } else {
    x = y;
  }
}

// good
x = x || y || 1;

简单解释一下逻辑运算符，逻辑运算符主要有两种，一个是 || 逻辑或，一个是 && 逻辑与。

逻辑或 ||：当前一个为真时，返回前一个值，前一个为假时返回后一个值。

var x = 1;
console.log(x || 2); // 1

var y = 0;
console.log(y || 2); // 2

逻辑与 &&：当前一个为真时，返回后一个值，前一个为假时返回前一个值。

var x = 1;
console.log(x && 2); // 2

var y = 0;
console.log(y && 2); // 0

其他 ESlint

for-in 里一定要有 hasOwnProperty 的判断；
不要在内置对象的原型上添加方法，如 Array, Date；
变量不要先使用后声明；
不要在一句代码中单单使用构造函数，记得将其赋值给某个变量；
不要在同个作用域下声明同名变量；
不要在一些不需要的地方加括号，例：delete(a.b)；
不要使用未声明的变量；
debugger 不要出现在提交的代码里；
数组中不要存在空元素；
不要在循环内部声明函数；
不要直接 new 使用构造函数（new Vue() 除外）；
不要声明了变量却不使用；

这些都可以参考 eslint-config-alloy，有详细的 JS、TS、React、Vue 的规范，我们后续配置 eslint 时也是引入腾讯的 eslint 规范。

// good
for (key in obj) {
  if (obj.hasOwnProperty(key)) {
    // be sure that obj[key] belongs to the object and was not inherited
    console.log(obj[key]);
  }
}

// not good
Array.prototype.count = function(value) {
  return 4;
};

// not good
function test() {
  console.log(x);

  var x = 1;
}

// not good
new Person();

// good
var person = new Person();

// not good
delete (obj.attr);

// good
delete obj.attr;

// not good
var a = [1, , , 2, 3];

// not good
var nums = [];

// not good
for (var i = 0; i < 10; i++) {
  (function(i) {
    nums[i] = function(j) {
      return i + j;
    };
  })(i);
}

其他

换行符统一用'LF'；
对上下文 this 的引用只能使用'_this', 'that', 'self'其中一个来命名；
行尾不要有空白字符；
不允许有空的代码块（如果实在需要，可以在代码块中写注释）。

// not good
function Person() {
  // not good
  var me = this;

  // good
  var _this = this;

  // good
  var that = this;

  // good
  var self = this;
}

if (condition) {
}

这一套规范我用 vuepress 做了一个网站进行存档，欢迎大家查看。www.shiyanping.top/code_rule，主要依附 github page 进行部署，也欢迎大家 star 我的 git 项目 github.com/Shiyanping/…。

阅读完后两部曲

非常感谢各位花时间阅读完，衷心希望各位小伙伴可以花少量的时间帮忙做两件事：

动动你的手指，帮忙点个赞吧，你的点赞是对我最大的动力。
希望各位关注一下我的公众号，新的文章第一时间发到公众号，公众号主要发一些个人随笔、读书笔记、还有一些技术热点和实时热点，并且还有非常吸引人的我个人自费抽奖活动哦~

制定自己团队的前端开发规范

命名规范

项目命名

目录命名

JS文件命名

CSS, SCSS文件命名

HTML文件命名

HTML 规范

语法：

标准模式

规定字符编码

IE 兼容模式

减少标签数量

语义化标签

CSS 规范

缩进

分号

注释

引号

命名

JavaScript 规范

缩进

变量命名

变量声明

单行长度

分号

空格

空行

换行

注释

单行注释

多行注释

函数注释

引号

对象，数组

括号

undefined

不允许存在多层嵌套的条件判断和循环（最多三层）

其他 ESlint

其他

相关链接

阅读完后两部曲