ECharts 源码代码规范

代码规范 - Apache EChartsApache ECharts，一款基于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。