Dojo Javascript 程式設計規格 規格自己的JavaScript書寫_基礎知識

前言

良好的JavaScript書寫習慣的優點不言而喻，今天彬Go向大家推薦Dojo Javascript 程式設計規範，相當不錯的 Javascript 程式設計風格規範，建議大家可​​以藉鏡一下此規範編寫 Javascript。感謝i.feelinglucky的翻譯。

序

Any violation to this guide is allowed if it enhances readability.

所有的程式碼都要變成可供他人容易閱讀的。

快讀參考

核心 API 請使用下面的風格：

结构	规则	注释
模块	小写	不要使用多重语义（Never multiple words）
类	骆驼
公有方法	混合	其他的外部调用也可以使用 lower_case()，这样的风格
公有变量	混合
常量	骆驼 或 大写

結構

規則

註釋

结构	规则
私有方法	混合，例子：_mixedCase
私有变量	混合，例子：_mixedCase
方法（method）参数	混合，例子：_mixedCase, mixedCase
本地（local）变量	混合，例子：_mixedCase, mixedCase

模組

小寫

不要使用多重語意（Never multiple words）

類別

駱駝

公有方法

混合

其他的外部呼叫也可以使用 lower_case()，這樣的風格

公有變數

混合

常數

駱駝 或 大寫

下面的雖然不是必要的，但建議使用：

結構	規則
私有方法	混合，範例：_mixedCase
私有變數	混合，範例：_mixedCase
方法（method）參數	混合，範例：_mixedCase, mixedCase
本地（local）變數	混合，範例：_mixedCase, mixedCase

命名規範

1.變數名稱 必須為 小寫字母。
2.類別的命名使用駱駝命名規則，例如：

Account, EventHandler

3.常數 必須 在物件（類別）或枚舉變數的前部宣告。枚舉變數的命名必須要有實際的意義，且其成員 必須 使用駱駝命名規則或使用大寫：

複製程式碼 程式碼如下:

var NodeTypes = {
Element : 1,
DOCUMENT: 2
}

4.簡寫單字 不能使用 大寫名稱作為變數名稱：

getInnerHtml(), getXml(), XmlDocument
5.方法的命令 必須 為動詞或動詞片語：

obj.getSomeValue()
6.公有類別的命名 必須 使用混合名稱（mixedCase）命名。
7.CSS 變數的命名 必須 使用其對應的相同的公共類別變數。
8.私有類別的變數屬性成員 必須 使用混合名稱（mixedCase）命名，並在前面底線（_）。例如：

複製程式碼 程式碼如下:

var MyClass = function(){
var _buffer;
this.doSomething = function(){
};
}

9.變數如果設定為私有，則前面 必須 新增底線。

this._somePrivateVariable = statement;

10.通用的變數 必須 使用與其名字一致的型別名稱：

setTopic(topic) // 變數 topic 為 Topic 類型的變數
11.所有的變數名 必須 使用英文名稱。
12.變數如有較廣的作用域（large scope），必須使用全域變數；此時可以設計成一個類別的成員。相對的如作用域較小或為私有變數則使用簡潔的單字命名。
13.如果變數有其隱含的回傳值，則避免使用其相似的方法：

getHandler(); // 避免使用 getEventHandler()

14.公有變數必須清楚的表達其自身的屬性，避免字義含糊不清，例如：

MouseEventHandler
，而非 MseEvtHdlr。
　　請再次注意這條規定，這樣做得的好處是非常明顯的。它能明確的表達式所定義的含義。例如：　　　

dojo.events.mouse.Handler // 而非 dojo.events.mouse.MouseEventHandler

15.類別/建構子 可以使用 擴充其基底類別的名稱命名，這樣可以正確、迅速的找到其基底類別的名稱：
　EventHandler
　UIEventHandler
　MouseEventHandler
　　基類可以在明確描述其屬性的前提下，縮減其命名：
　　　MouseEventHandler as opposed to MouseUIEventHandler.

特殊命名規範

術語 “get/set” 不要和一個欄位相連，除非它被定義為私有變數。
前面加 “is” 的變數名稱 應該 為布林值，同理可以是 “has”, “can” 或 “should”。
術語 “compute” 作為變數名應為已計算完成的變數。
術語 “find” 作為變數名應為已查找完成的變數。
術語 “initialize” 或 “init” 作為變數名稱應為已實例化（初始化）完成的類別或其他類型的變數。
UI （使用者介面）控制變數應在名稱後面加控制類型，例如： leftComboBox, TopScrollPane。
複數必須有其公開的名稱約定（原文：Plural form MUST be used to name collections）。
帶有 “num” 或 “count” 開頭的變數名稱約定為數字（物件）。
重複變數建議使用 “i”, “j”, “k” （依序類推）等名稱的變數。
補充用語必須使用補充詞，例如： get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
能縮寫的名稱盡量使用縮寫。
避免產生歧義的布林變數名稱，例如：
　　isNotError, isNotFound 為非法
錯誤類別建議在變數名稱後面加上 “Exception” 或 “Error”。
方法如果傳回一個類，則應該在名稱上說明傳回什麼；如果是一個過程，則應該說明做了什麼。

檔

縮排請使用 4 個空格符的製表位。
如果您的編輯器支援 檔案標籤_（file tags），請加添如下的一行使我們的程式碼更容易閱讀：

// vim:ts=4:noet:tw=0:
譯註：老外用 VIM 編輯器比較多，此條可以選擇遵循。

程式碼折疊必須看起來是完成並且是合乎邏輯的：

複製程式碼 程式碼如下:

var someExpression = Expression1
Expression2
Expression3;

var o = someObject.get(
Expression1,
Expression2,
Expression3
);

註：表達式的縮排與變數宣告應為一致的。
注意：函數的參數應採用明確的縮進，而縮排規則與其他區塊保持一致。

變數

1. 變數必須在宣告初始化以後才能使用，即便是 NULL 型別。
2. 變數不能產生歧義。
3. 相關的變數集應該放在同一程式碼區塊中，非相關的變數集不應該放在同一程式碼區塊中。
4. 變數應該盡量保持最小的生存週期。
5. 循環/重複變數的規格：
   1. 只有循環控制塊的話，則必須使用 FOR 迴圈。
   2. 迴圈變數應該在迴圈開始前就被初始化；如使用 FOR 迴圈，則使用 FOR 語句初始化迴圈變數。
   3. 「do … while」 語句是被允許的。
   4. “break” 和 “continue” 語句仍然允許使用（但請注意）。
6. 條件式
   1. 應該盡量避免複雜的條件表達式，如有必要可以使用臨時布林變數。
   2. The nominal case SHOULD be put in the “if” part and the exception in the “else” part of an “if” statement.
   3. 應避免在條件表達式中加入區塊。
7. 雜項
   1. 盡量避免幻數（Magic numbers），他們應該使用常數來代替。
   2. 浮點數變數必須指明小數點後一位（即使是 0）。
   3. 浮點數變數必須指明實部，即使它們為零（使用 0. 開頭）。

版面

塊

普通程式碼段 應該 看起來如下：

複製程式碼 程式碼如下:

while (!isDone){
doSomething();
isDone = moreToDo();
}

IF 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

if (someCondition){
statements;
} else if (someOtherCondition){
statements;
} else {
statements;
}

FOR 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

for (initialization; condition; update){
statements;
}

WHILE 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

while (!isDone) {
doSomething();
isDone = moreToDo();
}

DO … WHILE 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

do {
statements;
} while (condition);

SWITCH 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

switch (condition) {
case ABC:
statements;
// fallthrough
case DEF:
statements;
break;
default:
statements;
break;
}

TRY … CATCH 語句 應該 看起來像這樣：

複製程式碼 程式碼如下:

try {
statements;
} catch(ex) {
statements;
} finally {
statements;
}

單行的 IF – ELSE，WHILE 或 FOR 語句也 必須 加入括號，不過他們可以這樣寫：
if (condition){ statement; }
while (condition){ statement; }
for (intialization; condition; update){ statement; }

空白

1. 操作符 建議 使用空格隔開（包括三元運算子）。
2. 下面的關鍵字 避免使用 空白隔開：
   • break
   • catch
   • continue
   • do
   • else
   • finally
   • for
   • function （若為匿名函數，例如：var foo = function(){}; ）
   • if
   • return
   • switch
   • this
   • try
   • void
   • while
   • with
3. 下面的關鍵字必須使用空白隔開：
   • case
   • default
   • delete
   • function （若為申明，例如：function foo(){}; ）
   • in
   • instanceof
   • new
   • throw
   • typeof
   • var
4. 逗號（,） 建議 使用空白隔開。
5. 冒號（:） 建議 使用空白隔開。
6. 點（.） 在後部 建議 使用空白隔開。
7. 點（.） 避免 在前部使用空白。
8. 函數呼叫與方法 避免 使用空白，例如： doSomething(someParameter); // 而非 doSomething (someParameter)
9. 邏輯塊 之間使用空白行。
10. 聲明 建議 對齊使其更容易閱讀。

註解

1. 生澀的程式碼就 沒有必要 添加註解了，首先您需要 重寫
重寫
3. 重寫> 它們。 所有的註解請使用英文。 從已解決的方案到未開發的功能，註釋
4. 必須 與程式碼相關。 大量的變數申明後
5. 必須
6. 跟著一段註解。 註解需要說明的是程式碼段的用處，尤其是接下來的程式碼段。 註解

沒有必要

每行都新增。

文件

下面提供了一些基本的函數或物件的描述方法：

總結（summary）: 簡短的表述此函數或物件實現的目的 描述（description）: 對於此函數或類別的簡短的描述 返回（return）: 描述此函數傳回什麼（不包括返回類型） 基本函數資訊

複製程式碼


程式碼如下:


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?
}

函數的宣告

在有的情況下，對於函數的呼叫和宣告是隱義（invisible）的。在這種情況下，我們沒有辦法在函數中加入說明等（供程式呼叫）。如果您遭遇了這種情況，您可以使用一個類別來封裝函數。

註：此此方法只能在函數沒有初始化的參數情況下。如過不是，則它們會被忽略。

複製程式碼 程式碼如下:

dojo.declare(
"foo",
null,
{
// summary: Phew, this sure is relaxing, Fr​​ylock.
// 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.
}
);

參數

1. 簡單型
   　　　簡單的類型的參數可以直接在函數參數定義中註解說明。
   [cc lang="javascript"]function(/*String*/ foo, /*int*/ bar)...
   可變型別參數
   　　下面是幾個修飾符供參考：
   ?可選參數
   … 說面參數範圍不確定
   數組
   function(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
   全域參數描述
   　如果你想增加一個描述，你可以將它們移至初始化區塊。
   基本資訊格式為： *關鍵字* 描述欄位 （ *key* Descriptive sentence）
   參數和變數的格式為： *關鍵字* ~*類型*~ 描述欄位 （ *key* ~*type*~ Descriptive sentence）
   註： *關鍵字* 和 ~*類型*~ 可以使用任何字母和數字表達。
   複製程式碼 程式碼如下:
   
   function (foo, bar) {
   // foo: String
   // used for being the first parameter
   // bar: int
   // used for being the second parameter
   }
   

   變數

   由於實例變數、原型變數和外部變數的宣告是一致的，所以有很多的方法宣告、修改變數。具體的如何定義和定位應在變數最先出現的位置指明變數的名稱、類型、作用域等資訊。

   複製程式碼 程式碼如下:
   
   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 dojo.debug(this.myString);
   dojo.debug(foo.separator);
   }
   }
   foo.separator = "=====";
   

   物件中的變數註解

   應使用和物件值和方法一致的標註方式，例如在他們聲明的時候：

   複製程式碼 程式碼如下:
   
   {
   // key: String
   // A simple value
   key: "value",
   // key2: String
   // Another simple value
   }
   

   傳回值

   因為函數可以同時傳回多個不同（類型）的值，所以在每個傳回值之後應加入傳回類型的註解。註解在行內註解即可，如果所有的傳回值為同一類型，則指明傳回的類型；如為多個不同的回傳值，則標註傳回類型為」mixed」。

   複製程式碼 程式碼如下:
   
   function() {
   if (arguments.length) {
   return "You passed argument(s)"; // String
   } else {
   return false; // 布林
   }
   }
   

   偽代碼（有待討論）

   有時候您需要在函數或類別中新增對於此函數和類別的功能性流程描述。如果您打算這樣做，您可以使用/*======== （= 字符最好出現5 次或更多），這樣做的好處就是可以不用將這些東西加入代碼（譯註：原作者的意思可能為代碼管理系統）。

   這樣看起來在 /*===== 和 =====*/ 會有非常長的一段註釋，等待功能調整完畢以後就可以考慮是否刪除。
   

   複製程式碼 程式碼如下:
   
   /*=====
   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);
   }
   

   原文連結：http://dojotoolkit.org/developer/StyleGuide
   翻譯（Translated by）：i.feelinglucky{at}gmail.com from http://www.gracecode.com