JavaScript 团队规范参考

引子

这是 CSS 团队规范参考 之后一直想写的一部分，后来和一起共事的人结合实际的项目情况，讨论过比较有针对性的 JavaScript 规范，在此基础上，结合个人的一些想法，弄出一个版本，当作参考。

• Origin
• My GitHub

规范

规范是一个团队里面共同遵守的约定。随着时间的推移，有很大可能性会发生变化。在实施中，结合实际项目情况不断的检验、思考、总结、调整，这样就可以逐渐形成最适合自身团队的规范。

原则

• 临时处理的代码需要注释，以便及时删掉。
• 块级别作用域用 const 或 let，不要使用 var。
• 声明引用变量时，统一使用 const， 因为这样可以防止被修改。
• 创建对象用字面量的方式，禁止使用 new 的方式，new 的方式无法预期结果。
• 声明对象属性名只能用驼峰形式。
• 对象中使用简写属性，简写属性和非简写属性分开写。
• 合并或浅复制对象时，使用 ... 替代 Object.assign() 。
• 使用命名函数表达式取代函数声明，原因见 issue。
• 不要修改参数的数据结构和原始值。
• 字符串用单引号。
• 使用全等比较。
• 要写分号。

命名

• 目录和文件名称使用驼峰形式。
• 命名语义化，层级相关语义。
• 目录层级不要超过 3 层。

代码风格

• 缩进
• 分号
• 空格
• 空行
• 换行
• 注释
• 括号
• 变量

缩进

使用 2 个空格。

分号

以下几种情况后需加分号：

• 变量声明
• 表达式
• return
• throw
• break
• continue
• do-while

空格

以下几种情况不需要空格：

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

以下几种情况需要空格：

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

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

// not good
var a = ( 1+2 )*3;

// good
var a = (1 + 2) * 3;

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

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

// not good
doSomething (item);

// good
doSomething(item);

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

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

空行

以下几种情况需要空行：

• 变量声明后（当变量声明在代码块的最后一行时，则无需空行）
• 注释前（当注释在代码块的第一行时，则无需空行）
• 代码块后（在函数调用、数组、对象中则无需空行）
• 文件最后保留一个空行

// 变量声明后
var x = 1;

// 当变量声明在代码块的最后一行时，则无需空行
if (x >= 1) {
  var y = x + 1;
}

var a = 2;

// 注释之前要有一个空行
a++;

function b() {
  // 当注释在代码块的第一行时，则无需空行
  return a;
}

// 代码块后
for (var i = 0; i < 2; i++) {
  if (true) {
    return false;
  }

  continue;
}

// not good
var obj = {
  foo: function() {
    return 1;
  },

  bar: function() {
    return 2;
  }
};

// not good
var foo = [
  2,
  function() {
    a++;
  },
  3
];

// good
var foo = {
  a: 2,
  b: function() {
    a++;
  },
  c: 3
};

换行

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

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

• 下列关键字后：else, catch, finally
• 代码块 { 前
  以下几种情况需要换行：
• 代码块 { 后和 } 前
• 变量赋值后

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

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

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

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

//  'else', 'catch', 'finally' 后不需要换行
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;

注释

• 单行注释单独一行
• 多行注释最少三行

// one row
var name = 'Tom';

/*
 * multi row
 */
var x = 1;

括号

下列关键字后必须有大括号（即使代码块的内容只有一行）：

• if
• else
• for
• while
• do
• switch
• try
• catch
• finally

变量

• 标准变量采用驼峰式命名
• ID 在变量名中全大写
• URL 在变量名中全大写
• Android 在变量名中大写第一个字母
• IOS 全部大写
• 常量全大写，用下划线连接

对比 ESLint

ESLint 的规则默认都是不启用的状态，官方提供了一个 recommended 的规则，详细见 ESLint Rules，从中可以发现：

• ESLint 对代码语法、逻辑、潜在问题、样式进行了更全面的考虑。
• ESLint 中包含的一些规则在实际过程中较容易进行辨别。
• recommended 规则大部分都普遍适用，基于这个规则可以更方便的进行选择定制。

规范 ESLint 化

基于 recommended 规则，根据 ESLint 已有的配置规则，以及上面总结的规范进行自选配置。

{
  "rules": {
    "eqeqeq": "always", // 要求使用 === 和 !==
    "no-caller": "error", // 禁用 caller 或 callee
    "no-new": "error", // 禁止使用 new 以避免产生副作用
    "no-new-func": "error", // 禁止对 Function 对象使用 new 操作符
    "no-new-wrappers": "error", // 禁止对 Function 对象使用 new 操作符
    "no-array-constructor": "error", // 禁止使用 Array 构造函数
    "no-iterator": "error", // 禁用 __iterator__ 属性
    "no-proto": "error", // 禁用 __proto__ 属性
    "no-use-before-define": "error", // 禁止定义前使用
    "quotes": ["error", "single"], // 强制使用一致的反勾号、双引号或单引号
    "indent": ["error", 2], // 强制使用一致的缩进

    "no-multi-spaces": "error", // 禁止出现多个空格
    "array-bracket-spacing": ["error", "always"], // 禁止或强制在括号内使用空格
    "block-spacing": "error", // 禁止或强制在代码块中开括号前和闭括号后有空格
    "comma-spacing": ["error", { "before": false, "after": true }], // 强制在逗号周围使用空格
    "func-call-spacing": ["error", "never"], // 要求或禁止在函数标识符和其调用之间有空格
    "key-spacing": ["error", { "beforeColon": false, "afterColon": true }], // 强制在对象字面量的键和值之间使用一致的空格
    "space-before-blocks": "error", // 要求或禁止语句块之前的空格
    "space-infix-ops": "error", // 要求中操作符周围有空格
    "arrow-spacing": "error", // 要求箭头函数的箭头之前或之后有空格
    "space-before-function-paren": ["error", "never"], // 禁止或强制圆括号内的空格
    "space-in-parens": ["error", "never"], // 禁止或强制圆括号内的空格

    "curly": "all", // 强制所有控制语句使用一致的括号风格
    "brace-style": "error", // 大括号风格要求
    "multiline-comment-style": ["error", "starred-block"], // 强制对多行注释使用特定风格
    "object-curly-newline": ["error", { "multiline": true }], // 强制在花括号内使用一致的换行符
    "eol-last": ["error", "always"], // 要求或禁止文件末尾保留一行空行
    "spaced-comment": ["error", "always"], // 要求或禁止在注释前有空白
    "comma-style": ["error", "last"], // 逗号风格
  }
}

参考资料

• Airbnb JavaScript Style Guide
• Google JavaScript Style Guide
• Jquery JavaScript Style Guide
• Code Guide by @AlloyTeam