DIV CSS 佈局教程網

Dojo JavaScript 撰寫規範整理:讓程式碼更好讀
編輯:關於JavaScript     

良好的 JavaScript 撰寫習慣,效益不言可喻。本文整理 Dojo Toolkit 的官方風格指南,這是一份相當完整的規範,值得借鏡。

本指南的任何違例,只要提升了可讀性,都是被允許的。

這句開場白定調了整份文件的精神:規範服務於可讀性,而非反之。

命名規則速查

結構規則備註
模組全小寫不要使用多個單字
類別駝峰(首字大寫)Account、EventHandler
公有方法混合大小寫其他外部呼叫也可用 lower_case()
公有變數混合大小寫
常數駝峰或全大寫
私有方法/變數混合,前綴底線_mixedCase
方法參數/區域變數混合_mixedCase 或 mixedCase

命名規範細則

  1. 變數名稱使用小寫字母開頭。
  2. 類別名稱採駝峰式,如 Account、EventHandler。
  3. 常數必須在物件(類別)或列舉變數的前部宣告。列舉變數的名稱要有實際意義,成員可用駝峰或全大寫:
    var NodeTypes = {
      Element  : 1,
      DOCUMENT : 2
    }
  4. 縮寫單字不得作為變數名稱,應寫完整的 getInnerHtml()、getXml()、XmlDocument。
  5. 方法名稱必須是動詞或動詞片語:obj.getSomeValue()。
  6. 公有類別變數使用混合大小寫。
  7. CSS 類別名稱應對應相同的公有類別變數名稱。
  8. 私有屬性使用混合大小寫並前綴底線:
    var MyClass = function(){
      var _buffer;
      this.doSomething = function(){
      };
    }
  9. 設為私有的變數,前面必須加底線:this._somePrivateVariable = statement;
  10. 通用變數應使用與其型別一致的名稱:setTopic(topic),其中 topic 為 Topic 型別。
  11. 所有變數名稱使用英文。
  12. 作用域廣的變數宜設計為類別成員;作用域小或私有的變數則可用簡潔的單字命名。
  13. 若變數有隱含的回傳值,避免使用相似的方法名:寫 getHandler() 而非 getEventHandler()。
  14. 公有變數必須清楚表達其屬性,避免語意含糊:寫 MouseEventHandler,而非 MseEvtHdlr。Dojo 的建議是 dojo.events.mouse.Handler 而非 dojo.events.mouse.MouseEventHandler,因為前面的命名空間已經說明了它是滑鼠事件。
  15. 類別可延伸其基底類別的名稱命名,以便快速辨認繼承關係: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 後綴。
  • 回傳物件的方法應在名稱中說明回傳什麼;執行動作的程序則說明做了什麼。

檔案與縮排

  • 縮進使用四個空白字元的 Tab 寬度。
  • 若編輯器支援檔案標籤,可加上 // 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. 迴圈相關:
    • 僅有迴圈控制時,必須使用 for。
    • 迴圈變數應在迴圈前初始化;使用 for 時在其語句中初始化。
    • do...while 是被允許的。
    • break 與 continue 仍可使用,但需注意。
  6. 條件運算式:
    • 避免複雜條件,必要時改用暫時的布林變數。
    • 一般情況放在 if 分支,例外情況放在 else 分支。
    • 避免在條件運算式中夾帶區塊。
  7. 其他:
    • 避免魔術數字,應以常數取代。
    • 浮點數必須標明小數點後一位,即使是 0。
    • 浮點數必須標明實部,即使為零(以 0. 開頭)。

版面配置

// 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; }

空白使用

  1. 運算子建議用空格隔開,含三元運算子。
  2. 以下關鍵字不加空格:break、catch、continue、do、else、finally、for、function(匿名函式時)、if、return、switch、this、try、void、while、with。
  3. 以下關鍵字必須加空格:case、default、delete、function(函式宣告時)、in、instanceof、new、throw、typeof、var。
  4. 逗號建議加空格。
  5. 冒號建議加空格。
  6. 句點在後方建議加空格,前方避免加空格。
  7. 函式呼叫與方法呼叫不加空格:doSomething(someParameter); 而非 doSomething (someParameter)。
  8. 邏輯區塊之間以空行分隔。
  9. 宣告建議對齊以便閱讀。

註解

  1. 晦澀難讀的程式碼不需要加註解——你需要的是重寫它。
  2. 所有註解使用英文。
  3. 從已解決的問題到未實作的功能,註解必須與程式碼相關。
  4. 大量變數宣告之後必須附註解。
  5. 註解應說明程式碼區塊的用途,尤其是接下來那段。
  6. 註解不需要每行都加。

文件註解格式

基本的函式描述包含三部分: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 寬度)已不完全符合今日慣例;但它在命名一致性與「註解不該掩蓋爛程式碼」這兩個觀點上,至今仍然成立。

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