良好的 JavaScript 撰寫習慣,效益不言可喻。本文整理 Dojo Toolkit 的官方風格指南,這是一份相當完整的規範,值得借鏡。
本指南的任何違例,只要提升了可讀性,都是被允許的。
這句開場白定調了整份文件的精神:規範服務於可讀性,而非反之。
| 結構 | 規則 | 備註 |
|---|---|---|
| 模組 | 全小寫 | 不要使用多個單字 |
| 類別 | 駝峰(首字大寫) | Account、EventHandler |
| 公有方法 | 混合大小寫 | 其他外部呼叫也可用 lower_case() |
| 公有變數 | 混合大小寫 | |
| 常數 | 駝峰或全大寫 | |
| 私有方法/變數 | 混合,前綴底線 | _mixedCase |
| 方法參數/區域變數 | 混合 | _mixedCase 或 mixedCase |
var NodeTypes = {
Element : 1,
DOCUMENT : 2
}obj.getSomeValue()。var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}this._somePrivateVariable = statement;setTopic(topic),其中 topic 為 Topic 型別。dojo.events.mouse.Handler 而非 dojo.events.mouse.MouseEventHandler,因為前面的命名空間已經說明了它是滑鼠事件。// vim:ts=4:noet:tw=0: 一行(視團隊是否使用 Vim 而定)。程式碼折行時,應讓結構看得出來是完整且合邏輯的:
var someExpression = Expression1
+ Expression2
+ Expression3;
var o = someObject.get(
Expression1,
Expression2,
Expression3
);續行的縮進應與變數宣告對齊;函式參數則採用明確一致的縮進。
// while
while (!isDone){
doSomething();
isDone = moreToDo();
}// if / else if / else
if (someCondition){
statements;
} else if (someOtherCondition){
statements;
} else {
statements;
}// for
for (initialization; condition; update){
statements;
}// do...while
do {
statements;
} while (condition);// switch
switch (condition) {
case ABC:
statements;
// fallthrough
case DEF:
statements;
break;
default:
statements;
break;
}// try...catch...finally
try {
statements;
} catch(ex) {
statements;
} finally {
statements;
}單行的 if-else、while、for 也必須加上大括號,但可以寫成:
if (condition){ statement; }
while (condition){ statement; }
for (intialization; condition; update){ statement; }doSomething(someParameter); 而非 doSomething (someParameter)。基本的函式描述包含三部分:summary(簡短說明目的)、description(較詳細的描述)、returns(說明回傳什麼,不含型別)。
function(){
// summary: 說明這個函式要做什麼
// description: 補充說明
// returns: 說明回傳值
}簡單型別可直接寫在參數列表中:
function(/*String*/ foo, /*int*/ bar)...
修飾符約定:? 代表可選參數,... 代表數量不確定,[] 代表陣列。
function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
若需要較長的描述,可移到函式內的宣告區:
function (foo, bar) {
// foo: String
// 作為第一個參數使用
// bar: int
// 作為第二個參數使用
}function foo() {
// myString: String
// times: int
// 要印出 myString 的次數
// separator: String
// myString 之間要插入的字元
this.myString = "placeholder text";
this.times = 5;
}由於函式可能回傳多種型別,每個 return 後面都應標註型別;若全部同一型別則標明該型別,若有多種則標註 mixed。
function() {
if (arguments.length) {
return "You passed argument(s)"; // String
} else {
return false; // Boolean
}
}原文出處:Dojo Toolkit Style Guide。
這份規範年代久遠,其中部分建議(如註解使用英文、Tab 寬度)已不完全符合今日慣例;但它在命名一致性與「註解不該掩蓋爛程式碼」這兩個觀點上,至今仍然成立。