轉(zhuǎn) http://code.google.com/p/grace/wiki/DojoStyle
相當(dāng)不錯的 Javascript 編程風(fēng)格規(guī)范，建議大家采用此規(guī)范編寫 Javascript。原文鏈接： http://dojotoolkit.org/developer/StyleGuide 。
翻譯（Translated by）：i.feelinglucky{at}gmail.com from http://www.gracecode.com ，轉(zhuǎn)載請注明出處、作者和翻譯者，謝謝配合。
本文地址： http://code.google.com/p/grace/wiki/DojoStyle 。
Any violation to this guide is allowed if it enhances readability.
所有的代碼都要變成可供他人容易閱讀的。
核心 API 請使用下面的風(fēng)格：
| 結(jié)構(gòu) |
規(guī)則 |
注釋 |
| 模塊 |
小寫 |
不要使用多重語義（Never multiple words） |
| 類 |
駱駝 |
|
| 公有方法 |
混合 |
其他的外部調(diào)用也可以使用 lower_case()，這樣的風(fēng)格 |
| 公有變量 |
混合 |
|
| 常量 |
駱駝 或 大寫 |
|
下面的雖然不是必要的，但建議使用：
| 結(jié)構(gòu) |
規(guī)則 |
| 私有方法 |
混合，例子：_mixedCase |
| 私有變量 |
混合，例子：_mixedCase |
| 方法（method）參數(shù) |
混合，例子：_mixedCase, mixedCase |
| 本地（local）變量 |
混合，例子：_mixedCase, mixedCase |
- 變量名稱 必須為 小寫字母。
- 類的命名使用駱駝命名規(guī)則，例如：
Account, EventHandler
- 常量 必須 在對象（類）或者枚舉變量的前部聲明。枚舉變量的命名必須要有實際的意義，并且其成員 必須 使用駱駝命名規(guī)則或使用大寫：
var NodeTypes = {
Element : 1,
DOCUMENT: 2
}
- 簡寫單詞 不能使用 大寫名稱作為變量名：
getInnerHtml(), getXml(), XmlDocument
- 方法的命令 必須 為動詞或者是動詞短語：
obj.getSomeValue()
- 公有類的命名 必須 使用混合名稱（mixedCase）命名。
- CSS 變量的命名 必須 使用其對應(yīng)的相同的公共類變量。
- 私有類的變量屬性成員 必須 使用混合名稱（mixedCase）命名，并前面下下劃線（_）。例如：
var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}
- 變量如果設(shè)置為私有，則前面 必須 添加下劃線。
this._somePrivateVariable = statement;
- 通用的變量 必須 使用與其名字一致的類型名稱：
setTopic(topic) // 變量 topic 為 Topic 類型的變量
- 所有的變量名 必須 使用英文名稱。
- 變量如有較廣的作用域（large scope），必須使用全局變量；此時可以設(shè)計成一個類的成員。相對的如作用域較小或為私有變量則使用簡潔的單詞命名。
- 如果變量有其隱含的返回值，則避免使用其相似的方法：
getHandler(); // 避免使用 getEventHandler()
- 公有變量必須清楚的表達(dá)其自身的屬性，避免字義含糊不清，例如：
MouseEventHandler，而非 MseEvtHdlr。
請再次注意這條規(guī)定，這樣做得的好處是非常明顯的。它能明確的表達(dá)表達(dá)式所定義的含義。例如：
dojo.events.mouse.Handler // 而非 dojo.events.mouse.MouseEventHandler
- 類/構(gòu)造函數(shù) 可以使用 擴(kuò)展其基類的名稱命名，這樣可以正確、迅速的找到其基類的名稱：
EventHandler
UIEventHandler
MouseEventHandler
基類可以在明確描述其屬性的前提下，縮減其命名：
MouseEventHandler as opposed to MouseUIEventHandler.
- 術(shù)語 "get/set" 不要和一個字段相連，除非它被定義為私有變量。
- 前面加 "is" 的變量名 應(yīng)該 為布爾值，同理可以為 "has", "can" 或者 "should"。
- 術(shù)語 "compute" 作為變量名應(yīng)為已經(jīng)計算完成的變量。
- 術(shù)語 "find" 作為變量名應(yīng)為已經(jīng)查找完成的變量。
- 術(shù)語 "initialize" 或者 "init" 作為變量名應(yīng)為已經(jīng)實例化（初始化）完成的類或者其他類型的變量。
- UI （用戶界面）控制變量應(yīng)在名稱后加控制類型，例如： leftComboBox, TopScrollPane。
- 復(fù)數(shù)必須有其公共的名稱約定（原文：Plural form MUST be used to name collections）。
- 帶有 "num" 或者 "count" 開頭的變量名約定為數(shù)字（對象）。
- 重復(fù)變量建議使用 "i", "j", "k" （依次類推）等名稱的變量。
- 補(bǔ)充用語必須使用補(bǔ)充詞，例如： get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
- 能縮寫的名稱盡量使用縮寫。
- 避免產(chǎn)生歧義的布爾變量名稱，例如：
isNotError, isNotFound 為非法
- 錯誤類建議在變量名稱后加上 "Exception" 或者 "Error"。
- 方法如果返回一個類，則應(yīng)該在名稱上說明返回什么；如果是一個過程，則應(yīng)該說明做了什么。
- 縮進(jìn)請使用 4 個空白符的制表位。
- 如果您的編輯器支持 文件標(biāo)簽_（file tags），請加添如下的一行使我們的代碼更容易閱讀：
// vim:ts=4:noet:tw=0:
譯注：老外用 VIM 編輯器比較多，此條可以選擇遵循。
- 代碼折疊必須看起來是完成并且是合乎邏輯的：
var someExpression = Expression1
+ Expression2
+ Expression3;
var o = someObject.get(
Expression1,
Expression2,
Expression3
);
注：表達(dá)式的縮進(jìn)與變量聲明應(yīng)為一致的。
注：函數(shù)的參數(shù)應(yīng)采用明確的縮進(jìn)，縮進(jìn)規(guī)則與其他塊保持一致。
- 變量必須在聲明初始化以后才能使用，即便是 NULL 類型。
- 變量不能產(chǎn)生歧義。
- 相關(guān)的變量集應(yīng)該放在同一代碼塊中，非相關(guān)的變量集不應(yīng)該放在同一代碼塊中。
- 變量應(yīng)該盡量保持最小的生存周期。
- 循環(huán)/重復(fù)變量的規(guī)范：
- 只有循環(huán)控制塊的話，則必須使用 FOR 循環(huán)。
- 循環(huán)變量應(yīng)該在循環(huán)開始前就被初始化；如使用 FOR 循環(huán)，則使用 FOR 語句初始化循環(huán)變量。
- "do ... while" 語句是被允許的。
- "break" 和 "continue" 語句仍然允許使用（但請注意）。
- 條件表達(dá)式
- 應(yīng)該盡量避免復(fù)雜的條件表達(dá)式，如有必要可以使用臨時布爾變量。
- The nominal case SHOULD be put in the "if" part and the exception in the "else" part of an "if" statement.
- 應(yīng)避免在條件表達(dá)式中加入塊。
- 雜項
- 盡量避免幻數(shù)（Magic numbers），他們應(yīng)該使用常量來代替。
- 浮點變量必須指明小數(shù)點后一位（即使是 0）。
- 浮點變量必須指明實部，即使它們?yōu)榱悖ㄊ褂?0. 開頭）。
- 普通代碼段 應(yīng)該 看起來如下：
while (!isDone){
doSomething();
isDone = moreToDo();
}
- IF 語句 應(yīng)該 看起來像這樣：
if (someCondition){
statements;
} else if (someOtherCondition){
statements;
} else {
statements;
}
- FOR 語句 應(yīng)該 看起來像這樣：
for (initialization; condition; update){
statements;
}
- WHILE 語句 應(yīng)該 看起來像這樣：
while (!isDone) {
doSomething();
isDone = moreToDo();
}
- DO ... WHILE 語句 應(yīng)該 看起來像這樣：
do {
statements;
} while (condition);
- SWITCH 語句 應(yīng)該 看起來像這樣：
switch (condition) {
case ABC:
statements;
// fallthrough
case DEF:
statements;
break;
default:
statements;
break;
}
- TRY ... CATCH 語句 應(yīng)該 看起來像這樣：
try {
statements;
} catch(ex) {
statements;
} finally {
statements;
}
- 單行的 IF - ELSE，WHILE 或者 FOR 語句也 必須 加入括號，不過他們可以這樣寫：
if (condition){ statement; }
while (condition){ statement; }
for (intialization; condition; update){ statement; }
- 操作符 建議 使用空格隔開（包括三元操作符）。
- 下面的關(guān)鍵字 避免使用 空白隔開：
- 下面的關(guān)鍵字必須使用空白隔開：
- 逗號（,） 建議 使用空白隔開。
- 冒號（:） 建議 使用空白隔開。
- 點（.） 在后部 建議 使用空白隔開。
- 點（.） 避免 在前部使用空白。
- 函數(shù)調(diào)用和方法 避免 使用空白，例如： doSomething(someParameter); // 而非 doSomething (someParameter)
- 邏輯塊 之間使用空行。
- 聲明 建議 對齊使其更容易閱讀。
- 生澀的代碼就 沒有必要 添加注釋了，首先您需要 重寫 它們。
- 所有的注釋請使用英文。
- 從已解決的方案到未開發(fā)的功能，注釋 必須 與代碼相關(guān)。
- 大量的變量申明后 必須 跟隨一段注釋。
- 注釋需要說明的是代碼段的用處，尤其是接下來的代碼段。
- 注釋 沒有必要 每行都添加。
下面提供了一些基本的函數(shù)或者對象的描述方法：
function(){
// summary: Soon we will have enough treasure to rule all of New Jersey.
// description: Or we could just get a new roomate.
// Look, you go find him. He don't yell at you.
// All I ever try to do is make him smile and sing around
// him and dance around him and he just lays into me.
// He told me to get in the freezer 'cause there was a carnival in there.
// returns: Look, a Bananarama tape!
}
沒有返回值描述
{
// summary: Dingle, engage the rainbow machine!
// description:
// Tell you what, I wish I was--oh my g--that beam,
// coming up like that, the speed, you might wanna adjust that.
// It really did a number on my back, there. I mean, and I don't
// wanna say whiplash, just yet, cause that's a little too far,
// but, you're insured, right?
}
在有的情況下，對于函數(shù)的調(diào)用和聲明是隱義（invisible）的。在這種情況下，我們沒有辦法在函數(shù)中加入說明等（供程序調(diào)用）。如果您遭遇了這種情況，您可以使用一個類來封裝函數(shù)。
注：此此方法只能在函數(shù)沒有初始化的參數(shù)情況下。如過不是，則它們會被忽略。
dojo.declare(
"foo",
null,
{
// summary: Phew, this sure is relaxing, Frylock.
// description:
// Thousands of years ago, before the dawn of
// man as we knew him, there was Sir Santa of Claus: an
// ape-like creature making crude and pointless toys out
// of dino-bones, hurling them at chimp-like creatures with
// crinkled hands regardless of how they behaved the
// previous year.
// returns: Unless Carl pays tribute to the Elfin Elders in space.
}
);
- 簡單類型
簡單的類型的參數(shù)可以直接在函數(shù)參數(shù)定義中注釋說明。
function(/*String*/ foo, /*int*/ bar)...
- 可變類型參數(shù)
下面是幾個修飾符供參考：
function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
- 全局參數(shù)描述
如果你想增加一個描述，你可以將它們移至初始化塊。
基本信息格式為： *關(guān)鍵字* 描述字段 （ *key* Descriptive sentence）
參數(shù)和變量的格式為： *關(guān)鍵字* ~*類型*~ 描述字段 （ *key* ~*type*~ Descriptive sentence）
注： *關(guān)鍵字* 和 ~*類型*~ 可以使用任何字母和數(shù)字表述。
function (foo, bar) {
// foo: String
// used for being the first parameter
// bar: int
// used for being the second parameter
}
由于實例變量、原型變量和外部變量的聲明是一致的，所以有很多的方法聲明、修改變量。具體的如何定義和定位應(yīng)在變量最先出現(xiàn)的位置指明變量的名稱、類型、作用域等信息。
function foo() {
// myString: String
// times: int
// How many times to print myString
// separator: String
// What to print out in between myString*
this.myString = "placeholder text";
this.times = 5;
}
foo.prototype.setString = function (myString) {
this.myString = myString;
}
foo.prototype.toString = function() {
for(int i = 0; i < this.times; i++) {
dojo.debug(this.myString);
dojo.debug(foo.separator);
}
}
foo.separator = "=====";
應(yīng)使用和對象值和方法一致的標(biāo)注方式，比如在他們聲明的時候：
{
// key: String
// A simple value
key: "value",
// key2: String
// Another simple value
}
因為函數(shù)可以同時返回多個不同（類型）的值，所以應(yīng)每個返回值之后加入返回類型的注釋。注釋在行內(nèi)注釋即可，如果所有的返回值為同一類型，則指明返回的類型；如為多個不同的返回值，則標(biāo)注返回類型為"mixed"。
function() {
if (arguments.length) {
return "You passed argument(s)"; // String
} else {
return false; // Boolean
}
}
有時候您需要在函數(shù)或者類中添加對于此函數(shù)和類的功能性流程描述。如果您打算這樣做，您可以使用 /*======== （= 字符最好出現(xiàn) 5 次或者更多），這樣做的好處就是可以不用將這些東西加入代碼（譯注：原作者的意思可能為代碼管理系統(tǒng)）。
這樣看起來在 /*===== 和 =====*/ 會有非常長的一段注釋，等待功能調(diào)整完畢以后就可以考慮是否刪除。
/*=====
module.pseudo.kwArgs = {
// url: String
// The location of the file
url: "",
// mimeType: String
// text/html, text/xml, etc
mimeType: ""
}
=====*/
function(/*module.pseudo.kwArgs*/ kwArgs){
dojo.debug(kwArgs.url);
dojo.debug(kwArgs.mimeType);
}