通用約定
通用約定
注釋
原則
- As short as possible（如無(wú)必要，勿增注釋?zhuān)罕M量提高代碼本身的清晰性、可讀性。
- As long as necessary（如有必要，盡量詳盡）：合理的注釋、空行排版等，可以讓代碼更易閱讀、更具美感。
單行注釋
必須獨(dú)占一行。// 后跟一個(gè)空格，縮進(jìn)與下一行被注釋說(shuō)明的代碼一致。
多行注釋
避免使用 /*...*/ 這樣的多行注釋。有多行注釋內(nèi)容時(shí)，使用多個(gè)單行注釋。
函數(shù)/方法注釋
- 函數(shù)/方法注釋必須包含函數(shù)說(shuō)明，有參數(shù)和返回值時(shí)必須使用注釋標(biāo)識(shí)。；
- 參數(shù)和返回值注釋必須包含類(lèi)型信息和說(shuō)明；
- 當(dāng)函數(shù)是內(nèi)部函數(shù)，外部不可訪問(wèn)時(shí)，可以使用 @inner 標(biāo)識(shí)；
/**
* 函數(shù)描述
*
* @param {string} p1 參數(shù)1的說(shuō)明
* @param {string} p2 參數(shù)2的說(shuō)明，比較長(zhǎng)
* 那就換行了.
* @param {number=} p3 參數(shù)3的說(shuō)明（可選）
* @return {Object} 返回值描述
*/
function foo(p1, p2, p3) {
var p3 = p3 || 10;
return {
p1: p1,
p2: p2,
p3: p3
};
}文件注釋
文件注釋用于告訴不熟悉這段代碼的讀者這個(gè)文件中包含哪些東西。 應(yīng)該提供文件的大體內(nèi)容, 它的作者, 依賴(lài)關(guān)系和兼容性信息。如下:
/** * @fileoverview Description of file, its uses and information * about its dependencies. * @author user@meizu.com (Firstname Lastname) * Copyright 2009 Meizu Inc. All Rights Reserved. */
命名
變量, 使用 Camel 命名法。
var loadingModules = {};私有屬性、變量和方法以下劃線 _ 開(kāi)頭。
var _privateMethod = {};常量, 使用全部字母大寫(xiě)，單詞間下劃線分隔的命名方式。
var HTML_ENTITY = {};- 函數(shù), 使用 Camel 命名法。
- 函數(shù)的參數(shù), 使用 Camel 命名法。
function stringFormat(source) {}
function hear(theBells) {}- 類(lèi), 使用 Pascal 命名法
- 類(lèi)的 方法 / 屬性, 使用 Camel 命名法
function TextNode(value, engine) {
this.value = value;
this.engine = engine;
}
TextNode.prototype.clone = function () {
return this;
};- 枚舉變量 使用 Pascal 命名法。
- 枚舉的屬性， 使用全部字母大寫(xiě)，單詞間下劃線分隔的命名方式。
var TargetState = {
READING: 1,
READED: 2,
APPLIED: 3,
READY: 4};由多個(gè)單詞組成的 縮寫(xiě)詞，在命名中，根據(jù)當(dāng)前命名法和出現(xiàn)的位置，所有字母的大小寫(xiě)與首字母的大小寫(xiě)保持一致。
function XMLParser() {}
function insertHTML(element, html) {}
var httpRequest = new HTTPRequest();命名語(yǔ)法
類(lèi)名，使用名詞。
function Engine(options) {}函數(shù)名，使用動(dòng)賓短語(yǔ)。
function getStyle(element) {}boolean 類(lèi)型的變量使用 is 或 has 開(kāi)頭。
var isReady = false;var hasMoreCommands = false;
Promise 對(duì)象用動(dòng)賓短語(yǔ)的進(jìn)行時(shí)表達(dá)。
var loadingData = ajax.get('url');
loadingData.then(callback);接口命名規(guī)范
- 可讀性強(qiáng)，見(jiàn)名曉義；
- 盡量不與 jQuery 社區(qū)已有的習(xí)慣沖突；
- 盡量寫(xiě)全。不用縮寫(xiě)，除非是下面列表中約定的；（變量以表達(dá)清楚為目標(biāo)，uglify 會(huì)完成壓縮體積工作）
True 和 False 布爾表達(dá)式
類(lèi)型檢測(cè)優(yōu)先使用 typeof。對(duì)象類(lèi)型檢測(cè)使用 instanceof。null 或 undefined 的檢測(cè)使用 == null。
下面的布爾表達(dá)式都返回 false:
- null
- undefined
- '' 空字符串
- 0 數(shù)字0
但小心下面的, 可都返回 true:
- '0' 字符串0
- [] 空數(shù)組
- {} 空對(duì)象
不要在 Array 上使用 for-in 循環(huán)
for-in 循環(huán)只用于 object/map/hash 的遍歷, 對(duì) Array 用 for-in 循環(huán)有時(shí)會(huì)出錯(cuò). 因?yàn)樗⒉皇菑?0 到 length - 1 進(jìn)行遍歷, 而是所有出現(xiàn)在對(duì)象及其原型鏈的鍵值。
// Not recommended
function printArray(arr) {
for (var key in arr) {
print(arr[key]);
}
}
printArray([0,1,2,3]); // This works.
var a = new Array(10);
printArray(a); // This is wrong.
a = document.getElementsByTagName('*');
printArray(a); // This is wrong.
a = [0,1,2,3];
a.buhu = 'wine';
printArray(a); // This is wrong again.
a = new Array;
a[3] = 3;
printArray(a); // This is wrong again.
// Recommended
function printArray(arr) {
var l = arr.length;
for (var i = 0; i < l; i++) {
print(arr[i]);
}
}二元和三元操作符
操作符始終寫(xiě)在前一行, 以免分號(hào)的隱式插入產(chǎn)生預(yù)想不到的問(wèn)題。
var x = a ? b : c; var y = a ? longButSimpleOperandB : longButSimpleOperandC; var z = a ? moreComplicatedB : moreComplicatedC;
. 操作符也是如此：
var x = foo.bar(). doSomething(). doSomethingElse();
條件(三元)操作符 (?:)
三元操作符用于替代 if 條件判斷語(yǔ)句。
// Not recommended
if (val != 0) {
return foo();
} else {
return bar();
}
// Recommended
return val ? foo() : bar();&& 和 ||
二元布爾操作符是可短路的, 只有在必要時(shí)才會(huì)計(jì)算到最后一項(xiàng)。
// Not recommended
function foo(opt_win) {
var win;
if (opt_win) {
win = opt_win;
} else {
win = window;
}
// ...
}
if (node) {
if (node.kids) {
if (node.kids[index]) {
foo(node.kids[index]);
}
}
}
// Recommended
function foo(opt_win) {
var win = opt_win || window;
// ...
}
var kid = node && node.kids && node.kids[index];
if (kid) {
foo(kid);
}