4.1. 通用約定

通用約定

注釋

原則

• As short as possible（如無必要，勿增注釋）：盡量提高代碼本身的清晰性、可讀性。
• As long as necessary（如有必要，盡量詳盡）：合理的注釋、空行排版等，可以讓代碼更易閱讀、更具美感。

單行注釋

必須獨占一行。//?后跟一個空格，縮進(jìn)與下一行被注釋說明的代碼一致。

多行注釋

避免使用?/*...*/?這樣的多行注釋。有多行注釋內(nèi)容時，使用多個單行注釋。

函數(shù)/方法注釋

1. 函數(shù)/方法注釋必須包含函數(shù)說明，有參數(shù)和返回值時必須使用注釋標(biāo)識。；
2. 參數(shù)和返回值注釋必須包含類型信息和說明；
3. 當(dāng)函數(shù)是內(nèi)部函數(shù)，外部不可訪問時，可以使用 @inner 標(biāo)識；

/**
 * 函數(shù)描述
 *
 * @param {string} p1 參數(shù)1的說明
 * @param {string} p2 參數(shù)2的說明，比較長
 *     那就換行了.
 * @param {number=} p3 參數(shù)3的說明（可選）
 * @return {Object} 返回值描述
 */
function foo(p1, p2, p3) {
    var p3 = p3 || 10;
    return {
        p1: p1,
        p2: p2,
        p3: p3
    };
}

文件注釋

文件注釋用于告訴不熟悉這段代碼的讀者這個文件中包含哪些東西。 應(yīng)該提供文件的大體內(nè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 = {};

私有屬性、變量和方法以下劃線 _ 開頭。

var _privateMethod = {};

常量, 使用全部字母大寫，單詞間下劃線分隔的命名方式。

var HTML_ENTITY = {};

1. 函數(shù), 使用 Camel 命名法。
2. 函數(shù)的參數(shù), 使用 Camel 命名法。

function stringFormat(source) {}

function hear(theBells) {}

1. 類, 使用 Pascal 命名法
2. 類的?方法 / 屬性, 使用 Camel 命名法

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

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

1. 枚舉變量?使用 Pascal 命名法。
2. 枚舉的屬性， 使用全部字母大寫，單詞間下劃線分隔的命名方式。

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

由多個單詞組成的?縮寫詞，在命名中，根據(jù)當(dāng)前命名法和出現(xiàn)的位置，所有字母的大小寫與首字母的大小寫保持一致。

function XMLParser() {}

function insertHTML(element, html) {}

var httpRequest = new HTTPRequest();

命名語法

類名，使用名詞。

function Engine(options) {}

函數(shù)名，使用動賓短語。

function getStyle(element) {}

boolean?類型的變量使用 is 或 has 開頭。

var isReady = false;
var hasMoreCommands = false;

Promise 對象用動賓短語的進(jìn)行時表達(dá)。

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

接口命名規(guī)范

1. 可讀性強(qiáng)，見名曉義；
2. 盡量不與 jQuery 社區(qū)已有的習(xí)慣沖突；
3. 盡量寫全。不用縮寫，除非是下面列表中約定的；（變量以表達(dá)清楚為目標(biāo)，uglify 會完成壓縮體積工作）

True 和 False 布爾表達(dá)式

類型檢測優(yōu)先使用 typeof。對象類型檢測使用 instanceof。null 或 undefined 的檢測使用 == null。

下面的布爾表達(dá)式都返回 false:

• null
• undefined
• '' 空字符串
• 0 數(shù)字0

但小心下面的, 可都返回 true:

• '0' 字符串0
• [] 空數(shù)組
• {} 空對象

不要在 Array 上使用 for-in 循環(huán)

for-in 循環(huán)只用于?object/map/hash?的遍歷, 對?Array?用 for-in 循環(huán)有時會出錯. 因為它并不是從 0 到 length - 1 進(jìn)行遍歷, 而是所有出現(xiàn)在對象及其原型鏈的鍵值。

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

二元和三元操作符

操作符始終寫在前一行, 以免分號的隱式插入產(chǎn)生預(yù)想不到的問題。

var x = a ? b : c;

var y = a ?
    longButSimpleOperandB : longButSimpleOperandC;

var z = a ?
        moreComplicatedB :
        moreComplicatedC;

.?操作符也是如此：

var x = foo.bar().
    doSomething().
    doSomethingElse();

條件(三元)操作符 (?:)

三元操作符用于替代 if 條件判斷語句。

// Not recommended
if (val != 0) {
  return foo();
} else {
  return bar();
}

// Recommended
return val ? foo() : bar();

&& 和 ||

二元布爾操作符是可短路的, 只有在必要時才會計算到最后一項。

// 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);
}