JavaScript编码规范-Baidu

JavaScript编码规范

2
代码风格

2.1
文件

JavaScript

BOM

UTF-8

2.2
结构

2.2.1
缩进

4

2

tab

switch

case

default

// good
switch (variable) {

case '1':
// do...
break;

case '2':
// do...
break;

default:
// do...

}

// bad
switch (variable) {

case '1':
// do...
break;

case '2':
// do...
break;

default:
// do...

}

2.2.2
空格

var a = !arr.length;
a++;
a = b + c;

{

// good
if (condition) {
}

while (condition) {
}

function funcName() {
}

// bad
if (condition){
}

while (condition){
}

function funcName(){
}

if
/ else / for / while / function / switch / do / try / catch / finally

// good
if (condition) {
}

while (condition) {
}

(function () {
})();

// bad
if(condition) {
}

while(condition) {
}

(function() {
})();

:

:

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

// bad
var obj = {
a : 1,
b:2,
c :3
};

(

// good
function funcName() {
}

var funcName = function funcName() {
};

funcName();

// bad
function funcName () {
}

var funcName = function funcName () {
};

funcName ();

,

;

// good
callFunc(a, b);

// bad
callFunc(a , b) ;

if / for / while / switch / catch

()

[]

// good

callFunc(param1, param2, param3);

save(this.list[this.indexes[i]]);

needIncream && (variable += increament);

if (num > list.length) {
}

while (len--) {
}

// bad

callFunc( param1, param2, param3 );

save( this.list[ this.indexes[ i ] ] );

needIncreament && ( variable += increament );

if ( num > list.length ) {
}

while ( len-- ) {
}

{}

[]

// good
var arr1 = [];
var arr2 = [1, 2, 3];
var obj1 = {};
var obj2 = {name: 'obj'};
var obj3 = {
name: 'obj',
age: 20,
sex: 1
};

// bad
var arr1 = [ ];
var arr2 = [ 1, 2, 3 ];
var obj1 = { };
var obj2 = { name: 'obj' };
var obj3 = {name: 'obj', age: 20, sex: 1};

2.2.3
换行

120

// good
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')
|| user.hasAuthority('delete-admin')
) {
// Code
}

var result = number1 + number2 + number3
+ number4 + number5;

// bad
if (user.isAuthenticated() &&
user.isInRole('admin') &&
user.hasAuthority('add-admin') ||
user.hasAuthority('delete-admin')) {
// Code
}

var result = number1 + number2 + number3 +
number4 + number5;

,

;

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

foo(
aVeryVeryLongArgument,
anotherVeryLongArgument,
callback
);

// bad
var obj = {
a: 1
, b: 2
, c: 3
};

foo(
aVeryVeryLongArgument
, anotherVeryLongArgument
, callback
);

// 仅为按逻辑换行的示例，不代表setStyle的最优实现
function setStyle(element, property, value) {
if (element == null) {
return;
}

element.style[property] = value;
}

120

// 较复杂的逻辑条件组合，将每个条件独立一行，逻辑运算符放置在行首进行分隔，或将部分逻辑按逻辑组合进行分隔。
// 建议最终将右括号 ) 与左大括号 { 放在独立一行，保证与 if 内语句块能容易视觉辨识。
if (user.isAuthenticated()
&& user.isInRole('admin')
&& user.hasAuthority('add-admin')
|| user.hasAuthority('delete-admin')
) {
// Code
}

// 按一定长度截断字符串，并使用 + 运算符进行连接。
// 分隔字符串尽量按语义进行，如不要在一个完整的名词中间断开。
// 特别的，对于HTML片段的拼接，通过缩进，保持和HTML相同的结构。
var html = '' // 此处用一个空字符串，以便整个HTML片段都在新行严格对齐
+ '<article>'
+     '<h1>Title here</h1>'
+     '<p>This is a paragraph</p>'
+     '<footer>Complete</footer>'
+ '</article>';

// 也可使用数组来进行拼接，相对 + 更容易调整缩进。
var html = [
'<article>',
'<h1>Title here</h1>',
'<p>This is a paragraph</p>',
'<footer>Complete</footer>',
'</article>'
];
html = html.join('');

// 当参数过多时，将每个参数独立写在一行上，并将结束的右括号 ) 独立一行。
// 所有参数必须增加一个缩进。
foo(
aVeryVeryLongArgument,
anotherVeryLongArgument,
callback
);

// 也可以按逻辑对参数进行组合。
// 最经典的是baidu.format函数，调用时将参数分为“模板”和“数据”两块
baidu.format(
dateFormatTemplate,
year, month, date, hour, minute, second
);

// 当函数调用时，如果有一个或以上参数跨越多行，应当每一个参数独立一行。
// 这通常出现在匿名函数或者对象初始化等作为参数时，如setTimeout函数等。
setTimeout(
function () {
alert('hello');
},
200
);

order.data.read(
'id=' + me.model.id,
function (data) {
me.attchToModel(data.result);
callback();
},
300
);

// 链式调用较长时采用缩进进行调整。
$('#items')
.find('.selected')
.highlight()
.end();

// 三元运算符由3部分组成，因此其换行应当根据每个部分的长度不同，形成不同的情况。
var result = thisIsAVeryVeryLongCondition
? resultA : resultB;

var result = condition
? thisIsAVeryVeryLongResult
: resultB;

// 数组和对象初始化的混用，严格按照每个对象的 { 和结束 } 在独立一行的风格书写。
var array = [
{
// ...
},
{
// ...
}
];

if...else...

try...catch...finally

}

if (condition) {
// some statements;
}
else {
// some statements;
}

try {
// some statements;
}
catch (ex) {
// some statements;
}

2.2.4
语句

if / else / for / do / while

{...}

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

// bad
if (condition) callFunc();
if (condition)
callFunc();

// good
function funcName() {
}

// bad
function funcName() {
};

// 如果是函数表达式，分号是不允许省略的。
var funcName = function () {
};

IIFE

(

IIFE

(

// good
var task = (function () {
// Code
return result;
})();

var func = function () {
};

// bad
var task = function () {
// Code
return result;
}();

var func = (function () {
});

2.3
命名

变量

Camel命名法

var loadingModules = {};

常量

全部字母大写，单词间下划线分隔

var HTML_ENTITY = {};

函数

Camel命名法

function stringFormat(source) {
}

参数

Camel命名法

function hear(theBells) {
}

类

Pascal命名法

function TextNode(options) {
}

方法 / 属性

Camel命名法

function TextNode(value, engine) {
this.value = value;
this.engine = engine;
}

TextNode.prototype.clone = function () {
return this;
};

枚举变量

Pascal命名法

枚举的属性

全部字母大写，单词间下划线分隔

var TargetState = {
READING: 1,
READED: 2,
APPLIED: 3,
READY: 4
};

命名空间

Camel命名法

equipments.heavyWeapons = {};

function XMLParser() {
}

function insertHTML(element, html) {
}

var httpRequest = new HTTPRequest();

类名

名词

function Engine(options) {
}

函数名

动宾短语

function getStyle(element) {
}

boolean

is

has

var isReady = false;
var hasMoreCommands = false;

Promise对象

动宾短语的进行时

var loadingData = ajax.get('url');
loadingData.then(callback);

2.4
注释

2.4.1
单行注释

//

2.4.2
多行注释

/*...*/

2.4.3
文档化注释

/**...*/

2.4.4
类型定义

{

}

2.4.5
文件注释

@file

/**
* @file Describe the file
*/

@author

@author

@author

责任

@author

@author

@author

@author

/**
* @file Describe the file
* @author author-name(mail-name@domain.com)
*         author-name2(mail-name2@domain.com)
*/

2.4.6
命名空间注释

@namespace

/**
* @namespace
*/
var util = {};

2.4.7
类注释

@class

constructor

@constructor

/**
* 描述
*
* @class
*/
function Developer() {
// constructor body
}

@extends

/**
* 描述
*
* @class
* @extends Developer
*/
function Fronteer() {
Developer.call(this);
// constructor body
}
util.inherits(Fronteer, Developer);

@lends

@lends

/**
* 类描述
*
* @class
* @extends Developer
*/
function Fronteer() {
Developer.call(this);
// constructor body
}

util.extend(
Fronteer.prototype,
/** @lends Fronteer.prototype */{
_getLevel: function () {
// TODO
}
}
);

@public

@protected

@private

public

/**
* 类描述
*
* @class
* @extends Developer
*/
var Fronteer = function () {
Developer.call(this);

/**
* 属性描述
*
* @type {string}
* @private
*/
this._level = 'T12';

// constructor body
};
util.inherits(Fronteer, Developer);

/**
* 方法描述
*
* @private
* @return {string} 返回值描述
*/
Fronteer.prototype._getLevel = function () {
};

2.4.8
函数/方法注释

@inner

/**
* 函数描述
*
* @param {string} p1 参数1的说明
* @param {string} p2 参数2的说明，比较长
*     那就换行了.
* @param {number=} p3 参数3的说明（可选）
* @return {Object} 返回值描述
*/
function foo(p1, p2, p3) {
var p3 = p3 || 10;
return {
p1: p1,
p2: p2,
p3: p3
};
}

@param

/**
* 函数描述
*
* @param {Object} option 参数描述
* @param {string} option.url option项描述
* @param {string=} option.method option项描述，可选参数
*/
function foo(option) {
// TODO
}

@override

@param

@return

@override

2.4.9
事件注释

@event

/**
* 值变更时触发
*
* @event
* @param {Object} e e描述
* @param {string} e.before before描述
* @param {string} e.after after描述
*/
onchange: function (e) {
}

@fires

@event

@param

/**
* 点击处理
*
* @fires Select#change
* @private
*/
Select.prototype.clickHandler = function () {
/**
* 值变更时触发
*
* @event Select#change
* @param {Object} e e描述
* @param {string} e.before before描述
* @param {string} e.after after描述
*/
this.fire(
'change',
{
before: 'foo',
after: 'bar'
}
);
};

2.4.10
常量注释

@const

/**
* 常量说明
*
* @const
* @type {string}
*/
var REQUEST_URL = 'myurl.do';

2.4.11
复杂类型注释

@typedef

// `namespaceA~` 可以换成其它 namepaths 前缀，目的是为了生成文档中能显示 `@typedef` 定义的类型和链接。
/**
* 服务器
*
* @typedef {Object} namespaceA~Server
* @property {string} host 主机
* @property {number} port 端口
*/

/**
* 服务器列表
*
* @type {Array.<namespaceA~Server>}
*/
var servers = [
{
host: '1.2.3.4',
port: 8080
},
{
host: '1.2.3.5',
port: 8081
}
];

2.4.12
AMD 模块注释

@module

@exports

define(
function (require) {

/**
* foo description
*
* @exports Foo
*/
var foo = {
// TODO
};

/**
* baz description
*
* @return {boolean} return description
*/
foo.baz = function () {
// TODO
};

return foo;

}
);

define(
function (require) {

/**
* module description.
*
* @module foo
*/
var exports = {};

/**
* bar description
*
*/
exports.bar = function () {
// TODO
};

return exports;
}
);

/**
* module description.
*
* @module
*/
define(
function (require, exports) {

/**
* bar description
*
*/
exports.bar = function () {
// TODO
};
return exports;
}
);

@module

namepaths

module:

/**
* 点击处理
*
* @fires module:Select#change
* @private
*/
Select.prototype.clickHandler = function () {
/**
* 值变更时触发
*
* @event module:Select#change
* @param {Object} e e描述
* @param {string} e.before before描述
* @param {string} e.after after描述
*/
this.fire(
'change',
{
before: 'foo',
after: 'bar'
}
);
};

@alias

/**
* A module representing a jacket.
* @module jacket
*/
define(
function () {

/**
* @class
* @alias module:jacket
*/
var Jacket = function () {
};

return Jacket;
}
);

@exports

// one module
define('html/utils',
/**
* Utility functions to ease working with DOM elements.
* @exports html/utils
*/
function () {
var exports = {
};

return exports;
}
);

// another module
define('tag',
/** @exports tag */
function () {
var exports = {
};

return exports;
}
);

@namespace

@class

@exports

// 只使用 @class Bar 时，类方法和属性都必须增加 @name Bar#methodName 来标识，与 @exports 配合可以免除这一麻烦，并且在引用时可以省去 module: 前缀。
// 另外需要注意类名需要使用 var 定义的方式。

/**
* Bar description
*
* @see foo
* @exports  Bar
* @class
*/
var Bar = function () {
// TODO
};

/**
* baz description
*
* @return {(string|Array)} return description
*/
Bar.prototype.baz = function () {
// TODO
};

2.4.13
细节注释

[建议]
细节注释遵循单行注释的格式。说明必须换行时，每行是一个单行注释的起始。

function foo(p1, p2) {
// 这里对具体内部逻辑进行说明
// 说明太长需要换行
for (...) {
....
}
}

3
语言特性

3.1
变量

var

// good
var name = 'MyName';

// bad
name = 'MyName';

var

// good
var hangModules = [];
var missModules = [];
var visited = {};

// bad
var hangModules = [],
missModules = [],
visited = {};

即用即声明

// good
function kv2List(source) {
var list = [];

for (var key in source) {
if (source.hasOwnProperty(key)) {
var item = {
k: key,
v: source[key]
};
list.push(item);
}
}

return list;
}

// bad
function kv2List(source) {
var list = [];
var key;
var item;

for (key in source) {
if (source.hasOwnProperty(key)) {
item = {
k: key,
v: source[key]
};
list.push(item);
}
}

return list;
}

3.2
条件

===

==
null

// good
if (age === 30) {
// ......
}

// bad
if (age == 30) {
// ......
}

// 字符串为空

// good
if (!name) {
// ......
}

// bad
if (name === '') {
// ......
}

// 字符串非空

// good
if (name) {
// ......
}

// bad
if (name !== '') {
// ......
}

// 数组非空

// good
if (collection.length) {
// ......
}

// bad
if (collection.length > 0) {
// ......
}

// 布尔不成立

// good
if (!notTrue) {
// ......
}

// bad
if (notTrue === false) {
// ......
}

// null 或 undefined

// good
if (noValue == null) {
// ......
}

// bad
if (noValue === null || typeof noValue === 'undefined') {
// ......
}

switch

if

// good
switch (typeof variable) {
case 'object':
// ......
break;
case 'number':
case 'boolean':
case 'string':
// ......
break;
}

// bad
var type = typeof variable;
if (type === 'object') {
// ......
}
else if (type === 'number' || type === 'boolean' || type === 'string') {
// ......
}

else

else

// good
function getName() {
if (name) {
return name;
}

return 'unnamed';
}

// bad
function getName() {
if (name) {
return name;
}
else {
return 'unnamed';
}
}

3.3
循环

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

for (var i = 0, len = elements.length; i < len; i++) {
var element = elements[i];
addListener(element, 'click', clicker);
}

// bad
for (var i = 0, len = elements.length; i < len; i++) {
var element = elements[i];
addListener(element, 'click', function () {});
}

// good
var width = wrap.offsetWidth + 'px';
for (var i = 0, len = elements.length; i < len; i++) {
var element = elements[i];
element.style.width = width;
// ......
}

// bad
for (var i = 0, len = elements.length; i < len; i++) {
var element = elements[i];
element.style.width = wrap.offsetWidth + 'px';
// ......
}

length

for (var i = 0, len = elements.length; i < len; i++) {
var element = elements[i];
// ......
}

var len = elements.length;
while (len--) {
var element = elements[len];
// ......
}

3.4
类型

3.4.1
类型检测

typeof

instanceof

null

undefined

==
null

// string
typeof variable === 'string'

// number
typeof variable === 'number'

// boolean
typeof variable === 'boolean'

// Function
typeof variable === 'function'

// Object
typeof variable === 'object'

// RegExp
variable instanceof RegExp

// Array
variable instanceof Array

// null
variable === null

// null or undefined
variable == null

// undefined
typeof variable === 'undefined'

3.4.2
类型转换

string

+
''

// good
num + '';

// bad
new String(num);
num.toString();
String(num);

number

+

// good
+str;

// bad
Number(str);

string

number

parseInt

var width = '200px';
parseInt(width, 10);

parseInt

// good
parseInt(str, 10);

// bad
parseInt(str);

boolean

!!

var num = 3.14;
!!num;

number

Math.floor
/ Math.round / Math.ceil

parseInt

// good
var num = 3.14;
Math.ceil(num);

// bad
var num = 3.14;
parseInt(num, 10);

3.5
字符串

'

var str = '我是一个字符串';
var html = '<div class="cls">拼接HTML可以省去双引号转义</div>';

数组

+

// 使用数组拼接字符串
var str = [
// 推荐换行开始并缩进开始第一个字符串, 对齐代码, 方便阅读.
'<ul>',
'<li>第一项</li>',
'<li>第二项</li>',
'</ul>'
].join('');

// 使用 + 拼接字符串
var str2 = '' // 建议第一个为空字符串, 第二个换行开始并缩进开始, 对齐代码, 方便阅读
+ '<ul>',
+    '<li>第一项</li>',
+    '<li>第二项</li>',
+ '</ul>';

3.6
对象

{}

Object

// good
var obj = {};

// bad
var obj = new Object();

属性

属性

var info = {
name: 'someone',
age: 28
};

属性

属性

'

// good
var info = {
'name': 'someone',
'age': 28,
'more-info': '...'
};

// bad
var info = {
name: 'someone',
age: 28,
'more-info': '...'
};

// 以下行为绝对禁止
String.prototype.trim = function () {
};

.

.

[expr]

.

[expr]

info.age;
info['more-info'];

for
in

hasOwnProperty

var newInfo = {};
for (var key in info) {
if (info.hasOwnProperty(key)) {
newInfo[key] = info[key];
}
}

3.7
数组

[]

// good
var arr = [];

// bad
var arr = new Array();

for in

var arr = ['a', 'b', 'c'];
arr.other = 'other things'; // 这里仅作演示, 实际中应使用Object类型

// 正确的遍历方式
for (var i = 0, len = arr.length; i < len; i++) {
console.log(i);
}

// 错误的遍历方式
for (i in arr) {
console.log(i);
}

sort

.length = 0

3.8
函数

3.8.1
函数长度

50

function syncViewStateOnUserAction() {
if (x.checked) {
y.checked = true;
z.value = '';
}
else {
y.checked = false;
}

if (!a.value) {
warning.innerText = 'Please enter it';
submitButton.disabled = true;
}
else {
warning.innerText = '';
submitButton.disabled = false;
}
}

// 直接阅读该函数会难以明确其主线逻辑，因此下方是一种更合理的表达方式：

function syncViewStateOnUserAction() {
syncXStateToView();
checkAAvailability();
}

function syncXStateToView() {
if (x.checked) {
y.checked = true;
z.value = '';
}
else {
y.checked = false;
}
}

function checkAAvailability() {
if (!a.value) {
displayWarningForAMissing();
}
else {
clearWarnignForA();
}
}

3.8.2
参数设计

6

options

/**
* 移除某个元素
*
* @param {Node} element 需要移除的元素
* @param {boolean} removeEventListeners 是否同时将所有注册在元素上的事件移除
*/
function removeElement(element, removeEventListeners) {
element.parent.removeChild(element);
if (removeEventListeners) {
element.clearEventListeners();
}
}

/**
* 移除某个元素
*
* @param {Node} element 需要移除的元素
* @param {Object} options 相关的逻辑配置
* @param {boolean} options.removeEventListeners 是否同时将所有注册在元素上的事件移除
*/
function removeElement(element, options) {
element.parent.removeChild(element);
if (options.removeEventListeners) {
element.clearEventListeners();
}
}

3.8.3
闭包

null

IIFE

Lift
效应

var tasks = [];
for (var i = 0; i < 5; i++) {
tasks[tasks.length] = function () {
console.log('Current cursor is at ' + i);
};
}

var len = tasks.length;
while (len--) {
tasks[len]();
}

Current cursor is at 5

var tasks = [];
for (var i = 0; i < 5; i++) {
// 注意有一层额外的闭包
tasks[tasks.length] = (function (i) {
return function () {
console.log('Current cursor is at ' + i);
};
})(i);
}

var len = tasks.length;
while (len--) {
tasks[len]();
}

3.8.4
空函数

new Function()

var emptyFunction = function () {};

var EMPTY_FUNCTION = function () {};

function MyClass() {
}

MyClass.prototype.abstractMethod = EMPTY_FUNCTION;
MyClass.prototype.hooks.before = EMPTY_FUNCTION;
MyClass.prototype.hooks.after = EMPTY_FUNCTION;

3.9
面向对象

constructor

/**
* 构建类之间的继承关系
*
* @param {Function} subClass 子类函数
* @param {Function} superClass 父类函数
*/
function inherits(subClass, superClass) {
var F = new Function();
F.prototype = superClass.prototype;
subClass.prototype = new F();
subClass.prototype.constructor = subClass;
}

constructor

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

// 直接prototype等于对象时，需要修正constructor
Animal.prototype = {
constructor: Animal,

jump: function () {
alert('animal ' + this.name + ' jump');
}
};

// 这种方式扩展prototype则无需理会constructor
Animal.prototype.jump = function () {
alert('animal ' + this.name + ' jump');
};

function TextNode(value, engine) {
this.value = value;
this.engine = engine;
}

TextNode.prototype.clone = function () {
return this;
};

事件名

event

3.10
动态特性

3.10.1
eval

eval

eval

3.10.2
动态执行代码

new Function

var handler = new Function('x', 'y', 'return x + y;');
var result = handler($('#x').val(), $('#y').val());

3.10.3
with

with

3.10.4
delete

delete

delete

delete

delete

try {
delete o.x;
}
catch (deleteError) {
o.x = null;
}

3.10.5
对象属性

function Tree(datasource) {
this.datasource = datasource;
}

Tree.prototype.selectNode = function (id) {
// 从datasource中找出节点对象
var node = this.findNode(id);
if (node) {
node.selected = true;
this.flushView();
}
};

function Tree(datasource) {
this.datasource = datasource;
this.selectedNodeIndex = {};
}

Tree.prototype.selectNode = function (id) {
// 从datasource中找出节点对象
var node = this.findNode(id);
if (node) {
this.selectedNodeIndex[id] = true;
this.flushView();
}
};

4
浏览器环境

4.1
模块化

4.1.1
AMD

AMD

id

/

this/is/a/module

4.1.2
define

id

dependencies

define(
function (require) {
}
);

return

define(
function (require) {
var exports = {};

// ...

return exports;
}
);

4.1.3
require

require

async
require

// good
require(['foo'], function (foo) {
});

// bad
var foo = require('foo');

local require

global
require

require

relative
id

define(
function (require) {
var util = require('./util');
}
);

factory

require

define(
function (require) {
require('css!foo.css');
require('tpl!bar.tpl.html');

// ...
}
);

4.2
DOM

4.2.1
元素获取

document.getElementById

document.all

context.getElementsByTagName

context

document

tagName

*

<div></div>
<span></span>

<script>
var elements = document.getElementsByTagName('*');

// 显示为 DIV
alert(elements[0].tagName);

var div = elements[0];
var p = document.createElement('p');
docpment.body.insertBefore(p, div);

// 显示为 P
alert(elements[0].tagName);
</script>

children

childNodes

4.2.2
样式获取

getComputedStyle

currentStyle

4.2.3
样式设置

4.2.4
DOM 操作

DOM

reflow

DOM

4.2.5
DOM 事件

addEventListener / attachEvent

expando

addEventListener

false