ECharts 团队 JavaScript 代码规范要点梳理
最近看到一份不错的 JavaScript 代码简明规范，整理成笔记供参考。
原文地址：https://echarts.apache.org/zh/coding-standard.html
代码规范
源文件
- [强制] JavaScript 源文件必须以无 BOM 的 UTF-8 进行编码。
缩进
- [强制] 必须采用 4 个空格缩进，不允许以 Tab 制表符或 2 个空格代替。
- [强制]
switch中的case和default必须保持缩进。
// 正例
switch (variable) {
case '1':
// do...
break;
case '2':
// do...
break;
default:
// do...
}
// 反例
switch (variable) {
case '1':
// do...
break;
case '2':
// do...
break;
default:
// do...
}
空格
- [强制] 二元运算符两个操作数之间必须使用空格，但一元运算符与其操作数间不能有空格。
let a = !arr.length;
a++;
a = b + c;
- [强制] 在
{前必须有 1 个空格。
// 正例
if (condition) {}
set('attr', {
some: 'xxx',
any: 'yyy'
});
function funcName() {}
// 反例
if (condition){}
set('attr',{
some: 'xxx',
any: 'yyy'
});
function funcName(){}
- [强制]
if/else/for/while/function/switch/do/try/catch/finally等关键字与括号之间都必须加一个空格。
// 正例
if (condition) {}
while (condition) {}
(function () {})();
// 反例
if(condition) {}
while(condition) {}
(function() {})();
- [强制] 在创建对象的语句中，
:后必须加一个空格，:前不能有空格。
// 正例
const obj = {
a: 1,
b: 2,
c: 3
};
// 反例
const obj = {
a : 1,
b:2,
c :3
};
- [强制] 在函数声明、命名函数表达式和函数调用时，函数名称和
(间不能有空格。
// 正例
function funcName() {}
const funcName = function funcName() {};
funcName();
// 反例
function funcName () {}
const funcName = function funcName () {};
funcName ();
- [强制]
,和;前不能有空格。
// 正例
callFunc(a, b);
// 反例
callFunc(a , b) ;
- [强制]
(和[之后、)和]之前不能有空格。
// 正例
callFunc(param1, param2, param3);
save(this.list[this.indexes[i]]);
needIncream && (variable += increament);
if (num > list.length) {}
while (len--) {}
// 反例
callFunc( param1, param2, param3 );
save( this.list[ this.indexes[ i ] ] );
needIncreament && ( variable += increament );
if ( num > list.length ) {}
while ( len-- ) {}
// 正例
const arr1 = [];
const arr2 = [1, 2, 3];
const obj1 = {};
const obj2 = {name: 'obj'};
const obj3 = {
name: 'obj',
age: 20,
sex: 1
};
// 反例
const arr1 = [ ];
const arr2 = [ 1, 2, 3 ];
const obj1 = { };
const obj2 = { name: 'obj' };
const obj3 = {name: 'obj', age: 20, sex: 1};
- [强制] 每行代码后不能有尾随空格。
换行
- [强制] 必须在语句的结尾换行。
- [强制] 单行字符数不能超过 120 个，超出则需要换行。
- [强制] 如果需要换行，运算符必须放在新行的开头。
// 正例
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')
|| user.hasAuthority('delete-admin')) {
// Code
}
const result = number1 + number2 + number3
+ number4 + number5;
// 反例
if (user.isAuthenticated() &&
user.isInRole('admin') &&
user.hasAuthority('add-admin') ||
user.hasAuthority('delete-admin')) {
// Code
}
const result = number1 + number2 + number3 +
number4 + number5;
- [强制] 如果括号中的内容有多行，必须为
)、]、}另开一个新行，并使新行与(、[、{所在行的缩进相对应。
// 正例
if (product) {
product.load();
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')
) {
sendProduct(user, product);
}
}
const arr = [
'candy', 'sugar'
];
// 反例
if (product) {
product.load();
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')) {
sendProduct(user, product);
}
}
const arr = [
'candy', 'sugar'
];
- [强制]
,或;前不能有换行。
// 正例
const obj = {
a: 1,
b: 2,
c: 3
};
foo(
aVeryVeryLongArgument,
anotherVeryLongArgument,
callback
);
// 反例
const obj = {
a: 1
, b: 2
, c: 3
};
foo(
aVeryVeryLongArgument
, anotherVeryLongArgument
, callback
);
- [推荐] 建议换行和缩进遵循如下风格：
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')) {
// Code
}
foo(
aVeryVeryLongArgument,
anotherVeryLongArgument,
callback
);
baidu.format(
dateFormatTemplate,
year, month, date, hour, minute, second
);
$('#items')
.find('.selected')
.highlight()
.end();
const result = thisIsAVeryVeryLongCondition
? resultA : resultB;
const res = condition
? thisIsAVeryVeryLongResult
: resultB;
- [强制] 如果使用多行代码块，
else和catch必须另开一个新行。
// 正例
if (condition) {
// some statements;
}
else {
// some statements;
}
try {
// some statements;
}
catch (ex) {
// some statements;
}
// 反例
if (condition) {
// some statements;
} else {
// some statements;
}
try {
// some statements;
} catch (ex) {
// some statements;
}
语句
- [强制] 语句必须以
;结尾。 - [强制] 如果只有一行，
{}不能被省略。
// 正例
if (condition) {
callFunc();
}
// 反例
if (condition) callFunc();
if (condition)
callFunc();
- [强制] 函数定义的末尾不能有分号
;。
// 正例
function funcName() {}
// 反例
function funcName() {};
// 对于函数表达式，不能忽略分号
const funcName = function () {};
- [强制] 对象和数组的声明中不能有尾随逗号。
// 正例
const obj = {
attr1: 'xxx',
attr2: 'yyy'
};
const arr = [
'xxx',
'yyy'
];
// 反例
const obj = {
attr1: 'xxx',
attr2: 'yyy',
};
const arr = [
'xxx',
'yyy',
];
命名规约
- [强制] 变量名、属性名及函数名的命名必须遵循 lowerCamelCase（小骆驼拼写法）。
const loadingModules = {};
function loadProduct() {}
- [强制] class 类的命名必须遵循 UpperCamelCase (Pascal)，即大骆驼拼写法（帕斯卡拼写法）。
function Element(options) {}
- [推荐] 缩略词的所有字符应当一并大写或一并小写。
function parseSVG() {}
const svgParser;
语法特性
兼容性
语法特性可以通过一些工具方法进行弥补，但不能通过修改内置 JavaScript 对象的原型来实现。
// 正例
import * as zrUtil from 'zrender/src/core/util';
zrUtil.each(array, function (val, index) {
sum += val;
});
const result = zrUtil.map(array, function (val) {
return parse(val);
});
const pos = zrUtil.indexOf(array, val);
const obj2 = zrUtil.extend({}, obj1);
function Element() {
// ...
}
// 反例
array.forEach(function (val, index) {
sum += val;
});
let result = array.map(function (val) {
return parse(val);
});
const pos = array.indexOf(val);
const obj2 = Object.assign({}, obj1);
class Element {
// ...
}
String.prototype.trim = function () {};
变量
- [强制] 优先使用
const声明变量，且一行不能同时声明多个变量。
// 正例
const name = 'MyName';
const hangModules = [];
const missModules = [];
const visited = {};
// 反例
name = 'MyName';
const hangModules = [],
missModules = [],
visited = {};
条件判断
- [强制] 对于相等运算符，
==只能用于检查是否为null或者undefined，其余情况必须使用===。
// 正例
if (age === 30) {
// ...
}
if (type == null) {
// ...
}
// 反例
if (age == 30) {
// ...
}
- [推荐] 建议使用
xxx == null来判断null或undefined。 - [推荐] 尽量让
null和undefined的含义相同。也就是说，不要让用户或开发者去区分变量是null还是undefined。 - [推荐] 函数表达式或者函数声明不应该放在循环体中。
// 正例
function clicker() {
// ...
}
for (let i = 0, len = elements.length; i < len; i++) {
const element = elements[i];
addListener(element, 'click', clicker);
}
// 反例
for (let i = 0, len = elements.length; i < len; i++) {
const element = elements[i];
addListener(element, 'click', function () {});
}
类型转换
- [推荐] 建议使用
+ ''将值转为字符串。
// 正例
num + '';
// 反例
new String(num);
num.toString();
String(num);
- [推荐] 建议使用
+将值转为数值。
// 正例
+str;
// 反例
Number(str);
- [强制] 在使用
parseInt时，必须传入第二个参数。
// 正例
parseInt(str, 10);
// 反例
parseInt(str);
字符串，对象，数组
- [强制] 必须使用
'而不是"定义字符串。 - [强制] 必须使用对象字面量
{}来创建简单对象。
// 正例
const obj = {};
// 反例
const obj = new Object();
- [强制] 如果一个对象字面量的所有属性都不需要引号，引号必须省略。如果需要加引号，须使用
'而不是"。
// 正例
const info = {
name: 'someone',
age: 28
};
// 反例
const info = {
'name': 'someone',
'age': 28
};
const info2 = {
"age": 40
};
- [强制] 禁止修改内置对象的原型。
// 禁止
String.prototype.trim = function () {};
- [推荐] 尽可能使用
.而不是[]访问对象的属性。 - [推荐] 使用
for ... in ...时，应当注意使用hasOwnProperty以防Object的原型在某些运行时环境中被添加一些额外属性的情况。
const newInfo = {};
for (const key in info) {
if (info.hasOwnProperty(key)) {
newInfo[key] = info[key];
}
}
- [强制] 除非需要创建指定长度的数组，否则必须使用数组字面量
[]创建数组。
// 正例
const arr = [];
const arr2 = new Array(1e4);
// 反例
const arr = new Array();
- [强制] 不要使用
for in语句对数组进行遍历。
其他
- [强制] 不要使用
eval和with。允许使用new Function。
原文地址：https://echarts.apache.org/zh/coding-standard.html