DIV CSS 佈局教程網

Dojo JavaScript 風格指南:讓團隊程式碼讀起來更輕鬆
編輯:JavaScript基礎知識     

前言:好風格是給同事的體貼

寫程式碼不只是寫給機器執行,更是寫給人閱讀。本文整理自 Dojo Toolkit 官方公布的 JavaScript 風格指南,規則細緻、可操作性強,非常值得團隊借鑑。以下內容由 i.feelinglucky 翻譯整理。

指南開篇有句話值得記住:Any violation to this guide is allowed if it enhances readability. 也就是說,只要某種寫法能讓程式碼更好讀,違反規則是被允許的。規則的目的是可讀性,不是教条。

命名速查表

Dojo 核心 API 採用的命名約定如下:

結構規則備註
模組(module)全小寫不要使用多個單字拼接
類別(class)駝峰式(mixedCase)—
公開方法混合式外部呼叫也可採用 lower_case()
公開變數混合式—
常數駝峰或全大寫—

以下幾項並非強制,但官方建議採用:

結構規則
私有方法混合式,前綴下劃線,例如 _mixedCase
私有變數混合式,前綴下劃線,例如 _mixedCase
方法參數混合式,例如 _mixedCase、mixedCase
區域變數混合式,例如 _mixedCase、mixedCase

命名細則

  1. 變數名稱一律使用小寫字母開頭。
  2. 類別名稱採用駝峰式,例如 Account、EventHandler。
  3. 常數必須宣告在物件(類別)或列舉變數的前部。列舉變數本身要有實際意義,其成員可用駝峰式或全大寫。
var NodeTypes = {
  Element  : 1,
  DOCUMENT : 2
};
  1. 縮寫字不能只靠大寫來區分,應寫成完整可讀的形式:getInnerHtml()、getXml()、XmlDocument。
  2. 方法名稱必須是動詞或動詞片語,例如 obj.getSomeValue()。
  3. 公開類別的屬性使用混合式命名。
  4. CSS 類別名稱要與對應的公開類別變數一致。
  5. 私有成員使用混合式並加上前綴下劃線。
var MyClass = function(){
  var _buffer;
  this.doSomething = function(){
  };
}
  1. 標記為私有的變數,前面必須加上下劃線:this._somePrivateVariable = statement;
  2. 通用變數應使用與型別一致的命名:setTopic(topic),其中 topic 就是 Topic 型別。
  3. 所有變數名一律使用英文。
  4. 作用域大的變數應設計為類別成員;作用域小或私有的變數則可用簡潔的單字命名。
  5. 若方法只是回傳既有結果,避免使用會造成誤解的近似名稱:getHandler() 而非 getEventHandler()。
  6. 公開變數要清楚表達自身含義,不要採用含糊的縮寫:寫 MouseEventHandler 而不是 MseEvtHdlr;同時也別把命名空間重複放進名稱,寫 dojo.events.mouse.Handler 而不是 dojo.events.mouse.MouseEventHandler。
  7. 類別/建構子可以沿用它所擴充的基底類別名稱,這樣能快速看出繼承關係:EventHandler → UIEventHandler → MouseEventHandler。在語意清楚的前提下,名稱可以精簡,例如 MouseEventHandler 勝於 MouseUIEventHandler。

特殊命名約定

  • 「get/set」不要與普通欄位名稱連在一起,除非該欄位被定義為私有。
  • 以 is、has、can、should 開頭的名稱,值必須是布林。
  • 以 compute 命名的變數,代表已完成計算的結果。
  • 以 find 命名的變數,代表已完成搜尋的結果。
  • 以 initialize 或 init 命名的變數,代表已完成初始化的物件。
  • UI 控制項名稱要在後面標明類型,例如 leftComboBox、TopScrollPane。
  • 集合類型的命名要使用複數形式。
  • 以 num 或 count 開頭的名稱代表數字。
  • 迴圈計數變數建議依序使用 i、j、k。
  • 成對的操作要使用成對的動詞:get/set、add/remove、create/destroy、start/stop、insert/delete、begin/end 等。
  • 能縮寫的名稱盡量縮寫。
  • 避免語意反覆的布林名稱,isNotError、isNotFound 都不合格。
  • 錯誤類別名稱加上 Exception 或 Error 後綴。
  • 方法若回傳某個類別,名稱要說明回傳什麼;若只是執行一連串動作,名稱要說明做了什麼。

檔案排版

縮進使用 4 個空白字元的定位。若你的編輯器支援檔案標籤,可以加上這行讓格式更容易辨識(使用 Vim 的讀者可自行取捨):

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

換行處要讓程式碼看起來完整、合邏輯:

var someExpression = Expression1
                   + Expression2
                   + Expression3;

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

表達式的縮進應與變數宣告保持一致;函數參數也要有明確且一致的縮進。

變數使用守則

  1. 變數必須先宣告並初始化才能使用,即使初始值是 NULL。
  2. 變數命名不能產生歧義。
  3. 相關的變數集中放在同一區塊,不相關的變數不要混在一起。
  4. 盡量縮短變數的存活週期。
  5. 迴圈相關:
    • 只有迴圈控制流程時,使用 for 迴圈。
    • 迴圈變數應在進入迴圈前初始化;用 for 迴圈時就在 for 敘述中初始化。
    • do … while 是被允許的。
    • break 與 continue 仍可使用,但要留意可讀性。
  6. 條件運算式:
    • 避免過度複雜的條件判斷,必要時改用暫時的布林變數。
    • 正常情況放進 if 分支,例外情況放進 else 分支。
    • 不要在條件運算式中塞入區塊。
  7. 其他:
    • 避免魔術數字,改用常數表示。
    • 浮點數即使小數部分為 0,也要明確寫出小數點後一位。
    • 浮點數即使整數部分為 0,也要寫出 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 (initialization; 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. 函數呼叫與方法名稱和括號之間不留空白:doSomething(someParameter); 而非 doSomething (someParameter)。
  7. 不同邏輯區塊之間空一行。
  8. 宣告處建議對齊,方便閱讀。

註解原則

  1. 如果一段程式碼需要靠註解才能讀懂,先重寫它,而不是急著加註解。
  2. 所有註解使用英文撰寫。
  3. 註解必須與程式碼同步,從已解決的問題到尚未完成的功能都算。
  4. 大量變數宣告之後必須附上一段說明。
  5. 註解要說明「這段程式碼要做什麼」,尤其是接下來的那一段。
  6. 不需要每一行都加註解。

文件撰寫格式

函數與物件的基本描述包含三部分:summary(一句話說明目的)、description(較完整的描述)、returns(說明回傳內容,不含型別)。

function(){
  // summary: Soon we will have enough treasure to rule all of New Jersey.
  // description: Or we could just get a new roomate.
  // 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.
}

當函數的宣告與呼叫關係不明顯時,可以用類別包裝函數來承載文件說明:

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.
    // returns: Unless Carl pays tribute to the Elfin Elders in space.
  }
);

注意:這種寫法只在函數沒有具名參數時有效,否則註解會被忽略。

參數說明

簡單型別可以直接寫在參數列上:

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

可變型別的修飾符:? 代表可選參數,... 代表數量不確定,[] 代表陣列。

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

如果想補充描述,可以把說明移到函數主體的開頭,格式為「*key* ~*type*~ 描述」:

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 (var 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
}

回傳值說明

同一個函數可能回傳多種型別,因此每個 return 後面都要標註型別。若全部同型別就寫該型別,若型別不一則標為 mixed。

function() {
  if (arguments.length) {
    return "You passed argument(s)"; // String
  } else {
    return false; // Boolean
  }
}

虛擬碼區塊

若你想先寫出流程草稿,可以用 /* 加上至少五個等號包住,例如 /*===== 與 =====*/,實作完成後再決定是否移除。

/*=====
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);
}

原文出處:dojotoolkit.org/developer/StyleGuide 翻譯:i.feelinglucky(gracecode.com)

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved