# 通用約定
## 注釋
**原則**
* As short as possible（如無必要，勿增注釋）：盡量提高代碼本身的清晰性、可讀性。
* As long as necessary（如有必要，盡量詳盡）：合理的注釋、空行排版等，可以讓代碼更易閱讀、更具美感。
**單行注釋**
必須獨占一行。`//`?后跟一個空格，縮進與下一行被注釋說明的代碼一致。
**多行注釋**
避免使用?`/*...*/`?這樣的多行注釋。有多行注釋內容時，使用多個單行注釋。
**函數/方法注釋**
1. 函數/方法注釋必須包含函數說明，有參數和返回值時必須使用注釋標識。；
2. 參數和返回值注釋必須包含類型信息和說明；
3. 當函數是內部函數，外部不可訪問時，可以使用 @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
};
}
~~~
**文件注釋**
文件注釋用于告訴不熟悉這段代碼的讀者這個文件中包含哪些東西。 應該提供文件的大體內容, 它的作者, 依賴關系和兼容性信息。如下:
~~~
/**
* @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. **函數**, 使用 Camel 命名法。
2. 函數的**參數**, 使用 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
};
~~~
由多個單詞組成的?**縮寫詞**，在命名中，根據當前命名法和出現的位置，所有字母的大小寫與首字母的大小寫保持一致。
~~~
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);
~~~
## 接口命名規范
1. 可讀性強，見名曉義；
2. 盡量不與 jQuery 社區已有的習慣沖突；
3. 盡量寫全。不用縮寫，除非是下面列表中約定的；（變量以表達清楚為目標，uglify 會完成壓縮體積工作）
| 常用詞 | 說明 |
| --- | --- |
| options | 表示選項，與 jQuery 社區保持一致，不要用 config, opts 等 |
| active | 表示當前，不要用 current 等 |
| index | 表示索引，不要用 idx 等 |
| trigger | 觸點元素 |
| triggerType | 觸發類型、方式 |
| context | 表示傳入的 this 對象 |
| object | 推薦寫全，不推薦簡寫為 o, obj 等 |
| element | 推薦寫全，不推薦簡寫為 el, elem 等 |
| length | 不要寫成 len, l |
| prev | previous 的縮寫 |
| next | next 下一個 |
| constructor | 不能寫成 ctor |
| easing | 示動畫平滑函數 |
| min | minimize 的縮寫 |
| max | maximize 的縮寫 |
| DOM | 不要寫成 dom, Dom |
| .hbs | 使用 hbs 后綴表示模版 |
| btn | button 的縮寫 |
| link | 超鏈接 |
| title | 主要文本 |
| img | 圖片路徑（img標簽src屬性） |
| dataset | html5 data-xxx 數據接口 |
| theme | 主題 |
| className | 類名 |
| classNameSpace | class 命名空間 |
## True 和 False 布爾表達式
類型檢測優先使用 typeof。對象類型檢測使用 instanceof。null 或 undefined 的檢測使用 == null。
下面的布爾表達式都返回 false:
* null
* undefined
* '' 空字符串
* 0 數字0
但小心下面的, 可都返回 true:
* '0' 字符串0
* [] 空數組
* {} 空對象
## 不要在 Array 上使用 for-in 循環
for-in 循環只用于?`object/map/hash`?的遍歷, 對?`Array`?用 for-in 循環有時會出錯. 因為它并不是從 0 到 length - 1 進行遍歷, 而是所有出現在對象及其原型鏈的鍵值。
~~~
// 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]);
}
}
~~~
## 二元和三元操作符
操作符始終寫在前一行, 以免**分號的隱式插入**產生預想不到的問題。
~~~
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);
}
~~~
