Dojo Javascript 編程規範(轉)

前言

至關不錯的 Javascript 編程風格規範，建議你們採用此規範編寫 Javascript。原文連接： http://dojotoolkit.org/developer/StyleGuide 。

翻譯（Translated by）：i.feelinglucky{at}gmail.com from http://www.gracecode.com ，轉載請註明出處、做者和翻譯者，謝謝配合。

本文地址： http://code.google.com/p/grace/wiki/DojoStyle 。

序

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

 

命名規範

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

Account,EventHandler

1. 常量 必須 在對象（類）或者枚舉變量的前部聲明。枚舉變量的命名必需要有實際的意義，而且其成員 必須 使用駱駝命名規則或使用大寫：

varNodeTypes={     Element:1,     DOCUMENT:2}

1. 簡寫單詞 不能使用 大寫名稱做爲變量名：

getInnerHtml(), getXml(),XmlDocument

1. 方法的命令 必須 爲動詞或者是動詞短語：

obj.getSomeValue()

1. 公有類的命名 必須 使用混合名稱（mixedCase）命名。
2. CSS 變量的命名 必須 使用其對應的相同的公共類變量。
3. 私有類的變量屬性成員 必須 使用混合名稱（mixedCase）命名，並前面下下劃線（_）。例如：

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

1. 變量若是設置爲私有，則前面 必須 添加下劃線。

this._somePrivateVariable = statement;

1. 通用的變量 必須 使用與其名字一致的類型名稱：

setTopic(topic)// 變量 topic 爲 Topic 類型的變量

1. 全部的變量名 必須 使用英文名稱。
2. 變量若有較廣的做用域（large scope），必須使用全局變量；此時能夠設計成一個類的成員。相對的如做用域較小或爲私有變量則使用簡潔的單詞命名。
3. 若是變量有其隱含的返回值，則避免使用其類似的方法：

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

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

MouseEventHandler，而非MseEvtHdlr。

請再次注意這條規定，這樣作得的好處是很是明顯的。它能明確的表達表達式所定義的含義。例如： 

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

1. 類/構造函數 可使用 擴展其基類的名稱命名，這樣能夠正確、迅速的找到其基類的名稱：

EventHandlerUIEventHandlerMouseEventHandler

基類能夠在明確描述其屬性的前提下，縮減其命名： 

MouseEventHandleras opposed to MouseUIEventHandler.

特殊命名規範

1. 術語 "get/set" 不要和一個字段相連，除非它被定義爲私有變量。
2. 前面加 "is" 的變量名 應該 爲布爾值，同理能夠爲 "has", "can" 或者 "should"。
3. 術語 "compute" 做爲變量名應爲已經計算完成的變量。
4. 術語 "find" 做爲變量名應爲已經查找完成的變量。
5. 術語 "initialize" 或者 "init" 做爲變量名應爲已經實例化（初始化）完成的類或者其餘類型的變量。
6. UI （用戶界面）控制變量應在名稱後加控制類型，例如： leftComboBox, TopScrollPane。
7. 複數必須有其公共的名稱約定（原文：Plural form MUST be used to name collections）。
8. 帶有 "num" 或者 "count" 開頭的變量名約定爲數字（對象）。
9. 重複變量建議使用 "i", "j", "k" （依次類推）等名稱的變量。
10. 補充用語必須使用補充詞，例如： get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
11. 能縮寫的名稱儘可能使用縮寫。
12. 避免產生歧義的布爾變量名稱，例如：

isNotError, isNotFound 爲非法

1. 錯誤類建議在變量名稱後加上 "Exception" 或者 "Error"。
2. 方法若是返回一個類，則應該在名稱上說明返回什麼；若是是一個過程，則應該說明作了什麼。

文件

1. 縮進請使用 4 個空白符的製表位。
2. 若是您的編輯器支持 文件標籤_（file tags），請加添以下的一行使咱們的代碼更容易閱讀：

// vim:ts=4:noet:tw=0:

譯註：老外用 VIM 編輯器比較多，此條能夠選擇遵循。

1. 代碼摺疊必須看起來是完成而且是合乎邏輯的：

 

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. 開頭）。

佈局

塊

1. 普通代碼段 應該 看起來以下：

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

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

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

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

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

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

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

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

do{         statements;}while(condition);

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

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

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

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

1. 單行的 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. 生澀的代碼就 沒有必要 添加註釋了，首先您須要 重寫 它們。
2. 全部的註釋請使用英文。
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, 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.         });

參數

1. 簡單類型

簡單的類型的參數能夠直接在函數參數定義中註釋說明。 

function(/*String*/ foo,/*int*/ bar)...

1. 可變類型參數

下面是幾個修飾符供參考： 

• ? 可選參數
• ... 說面參數範圍不肯定
• 數組

function(/*String?*/ foo,/*int...*/ bar,/*String[]*/ baz)...

1. 全局參數描述

若是你想增長一個描述，你能夠將它們移至初始化塊。 

基本信息格式爲： *關鍵字* 描述字段 （ *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 <this.times; 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{         returnfalse;// Boolean     }}

僞代碼（有待討論）

有時候您須要在函數或者類中添加對於此函數和類的功能性流程描述。若是您打算這樣作，您可使用 /*======== （= 字符最好出現 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);}