1文檔信息
|
條目 |
內容 |
|
項目編號 |
通用 |
|
項目名稱 |
通用 |
|
標題 |
JavaScript編程規範 |
|
類別 |
規範文檔 |
|
當前 |
試用草稿 |
|
摘要 |
|
|
當前版本 |
V1.0 |
|
日期 |
2015/11/9 |
|
作者 |
徐維堅（xuweijian） |
|
文檔擁有者 |
內部公開 |
|
文件 |
前端規範系列-JavaScript篇.docx |
2修改歷史
|
編號 |
修訂人 |
修訂內容簡述 |
修訂 日期 |
修訂前 版本號 |
修訂後 版本號 |
|
V0001 |
徐維堅 |
編程規範文件編寫，草稿試用版公佈 |
2015/11/10 |
|
V1.0 |
|
|
|
|
|
|
|
規範前言
良好的編程規範對於軟件的開發與維護，至關重要！他不僅可以提高代碼的可讀性、可靠性、有效性、健壯性，而且利於幫助開發人員開發和維護代碼。對於一個團隊協作的項目來說，人員的變動，一個良好的編程規範，有助於後續開發者和新手快速瞭解項目代碼所要表現的含義。
1 範圍
本規範規定了使用JavaScript語言編程時排版、命名、聲明、作用域、及一些特殊符號的規則和建議。
本規範適用於使用JavaScript語言編程的產品和項目。
2 術語和定義
規則：編程時強制必須遵守的原則。
建議：編程時必須加以考慮的原則。
格式：對此規範格式的的說明。
說明：對此規範或建議進行必要的解釋。
實例/如：對此規範或建議從正、反兩個方面給出的例子。
1命名規範
1.1基本規則
規範的命名能使程序更易閱讀，從而更易於理解。它們也可以提供一些標識功能方面的信息，有助於更好的理解代碼和應用。
1） 規則一：使用可以準確說明變量、函數、原型(prototype)的完整英文描述符。嚴禁使用漢語拼音、不相關單詞及漢字進行命名，實例：firstName，listAllUsers或 CorporateCustomer等；
2） 規則二：儘量少用縮寫，但如果一定要使用或名稱過長（不超過 25 個字母），當使用公共縮寫和習慣縮寫等，如實現（implement）可縮寫成impl，經理（manager）可縮寫成mgr等，嚴禁濫用縮寫；
3） 規則三：變量命名必須以小寫字母開頭，命名使用駱峯命名規則；
4） 規則四：方法名必須使用動詞或動詞短語命名，實例：getIdcName()、export()等；
5） 規則五：避免使用相似或者僅在大小寫上有區別的名字，以免不嚴格區分大小寫的系統視爲同一名稱；
6） 規則六：避免命名中含有數字，但可以用2表示to，4表示for，另末尾使用數字表示同一系列的除外，如var$td_1 = $(‘.grid td’)[1];
7） 規則七：類名、構造函數、公共對象實例等名稱首字母大寫。
|
var MyCommon = { getSmallClassFromBigClass: function() {} } |
1.2相關建議
以下爲相關建議，非必要遵循，但需要考慮
1) 建議一：變量如果設置爲私有變量，函數爲私有函數，則前面添加下劃線進行標註；公有變量和函數不添加下劃線
|
實例一： var MyClass = function() { var _thisTotal = 0; var _doSomething = function() {}; this.getThisTotal = function() { return _thisTotal; }; }; var myClassInstance = new MyClass(); myClassInstance.total = myClassInstance. getThisTotal(); |
實例二： function MyClass() { this._thisTotal = 0; this._doSomething = function() {}; } MyClass.prototype.getThisTotal = function() { return this._thisTotal; }; var myClassInstance = new MyClass(); myClassInstance.total = myClassInstance.getThisTotal(); |
2) 建議二：前面加"is" 的變量名應該爲布爾值，同理 "has","can" 或者 "should"亦如此；
3) 建議三：重複變量建議使用"i", "j", "k" （依次類推）等名稱的變量；
4) 建議四：全局變量、常量應該全部大寫；
5) 建議五：術語"initialize" 或者 "init" 作爲變量名應爲已經實例化（初始化）完成的類或者其他類型的變量；爲函數，應爲初始化操作。
2代碼組織規範
基本原則：利於個人開發，便於相互交流。
【說明】：因個人習慣和編輯器等可以設置而形成自己獨特的風格，但必須前後一致，並符合本規範的基本規則、建議和格式。
2.1縮排
原則：
（1）代碼中以TAB（4個字符）縮進，在編輯器中請將TAB設置爲相同的長度，否則在不同編輯器或設置下會導致TAB長度不等而影響整個程序代碼的格式；
（2）同一代碼塊中的代碼對齊，這裏所說的代碼塊，包括但不限於：function、if else語句、while、for等，即使用{}包圍的代碼。
2.1註釋
原則：不吝惜代碼註釋，重要函數、變量必須添加註釋；特殊函數、變量、常量必須添加註釋。
註釋的格式，可參考如下所示：
1）變量註釋：
|
// 初始化序列號 var index = 0; |
var index = 0; // 初始化序列號 |
2）函數註釋，包括a.函數描述及其功能說明；b.參數描述應包括類型、參數名、參數描述；有返回值的需要對返回值進行相應描述：
|
/** * 綁定事件 * @param {Object} $detailDom 當前變更詳情頁面主體DOM對象 * @return null */ function _bindEvent($detailDom) {
|
|
/** * 查看專線詳情 * @param {jQueryObject} $grid 列表DOM容器 * @param {String} selector 需要添加詳情鏈接的選擇器 * @param {Boolean} needSpecialId 是否需要指定其他特定id，默認不傳，即false * @param {String} specialIdName needSpecialId爲true，此值必傳，即指定id的屬性名稱 * @return {Boolean} result 操作是否成功 */ viewDetail: function($grid, selector, needSpecialId, specialIdName) { var self = this;
|
3）文件註釋，應該包含文件描述、功能簡介和作者，還可以加上創建時間：
|
/** * 本js實現專線續費申請頁面所有功能 * @author xuweijian * @date 2015/10/12 15:25:33 */ $(function() { |
4）行註釋與塊註釋：使用 //…的註釋方法來註釋需要表明的內容；使用/**和*/註釋的方法來註釋需要表明的內容。
3 編碼規範
3.1 變量編碼規範
原則：在遵循命名規則之上，應遵守以下規則，
（1）申明多個變量，變量之間使用逗號分隔；同時建議逗號與變量之間添加一個空格，避免過於擁擠，或是換行申明（此時可以對某個變量添加註釋！），
|
實例一： var name = ‘’, value = ‘’, title = ‘’; |
實例二： var name = ‘’, value = ‘’, // 註釋 title = ‘’; |
（2）變量申明時，應明確變量的類型，可以立即賦值，儘量避免變量的類型在使用過程中被轉換；
（3）儘量避免魔數（Magicnumbers），他們應該使用常量來代替；
（4）聲明變量必須加上 var 關鍵字，否則將成爲全局變量（Document或者 Window），進而成爲污染全局的變量；
3.2 函數編碼規範
原則：
（1） 所有的函數在使用前進行聲明，內函數的聲明跟在var 語句的後面；
（2） 不要在語句塊（if…else等）內聲明一個函數；
其編碼風格應該遵循這幾點建議：
1） 建議一：函數名與參數()之間不要留有空格；
2） 建議二：參數列表之間使用逗號分隔，逗號與參數之間留有一個空格；
3） 建議三：使用右側簡約模式，)與{之間留一個空格；
4） 建議四：避免參數過多現象，一般不超5個，過多使用對象傳入；
5） 建議五：匿名函數不應該換行，如：$(‘#id’).bind(function(){…});中參數爲匿名函數不應該換行處理，函數的主體遵循前面建議與原則；
|
function outer(c，d) { var e = c * d; function inner(a， b) { return (e * a) + b; } return inner(0， 1); } |
// 簡約模式 function outer(c，d) { var e = c * d; function inner(a， b) { return (e * a) + b; } return inner(0， 1); }
|
在函數體中，我們應遵循以下建議：
1）建議一：避免提供多個出口；
|
//不要使用這種方式，當處理程序段很長時將很難找到出口點 if (condition) { return A; } else { return B; }
|
//建議使用如下方式 var result = null; if (condition) { result = A; } else { result = B; } return result; |
2）建議二：函數體中代碼不應過長，一般不要超過100行；
3.3表達式與語句
原則：表達式和語句應清晰、簡潔，易於閱讀和理解，避免使用晦澀難懂的語句。使用圓括號明確表達式執行優先級。
3.3.1控制語句
1）建議一：判斷中如有常量，則應將常量置與判斷式的右側。如：
|
if ( true == isAdmin())... if ( null == user)... |
2）建議二：boolean類型判斷語句儘量明確條件比較值true/false
|
//不建議使用 if (isCond)... if (!isCond)...
|
//儘量使用 if (true == isCond)… if (false == isCond)… if (true != isCond)… |
編碼風格應遵循以下建議：
（1） 建議一：if…else if…else語句必須使用{}將每個判斷條件後的執行語句括起來。
（2） 建議二：if…else if…else與小括號、大括號之間應該空一格；
（3） 建議三：條件中的變量與“==”、“===”之間應該空一格；
（4） 建議四：類型確定的變量，在比較時，應使用嚴格相等符“===”，即”0” ===0比較值是false。
3.3.2循環語句
原則：
（1） 循環中必須有終止循環的條件或語句，避免死循環。
（2） 當多層循環嵌套時，計數器變量注意不要有衝突。
（3） 注意循環條件在執行循環過程中是否會發生變化，如果會則必須把循環條件的值在執行循環前獲取而不要在每次循環去執行。
（4） 考慮運行效率問題也應把循環條件值放在循環執行前獲取。
建議：
（1） 使用最基本的for循環，儘量避免使用for …in循環；
（2） for …in循環可用於用於object/map/hash 的遍歷，對 Array 用 for-in 循環有時會出錯，不建議使用；
（3） for循環中條件語句，不應該每次執行一個操作（如計算），應該在初始語句中實現；
|
// 不建議每次查詢length的值 for (var i = 0; i < data.length; i++) {
} |
// 建議在初始語句中賦值一個變量 for (var i = 0, len = data.length; i < len; i++) {
} |
3.3.3語句規範
原則：
(1) 除了語句塊最後一條語句可以沒有分號“;”以外，每條語句必須以分號結束，以避免代碼壓縮後造成解析失敗。
(2) 當代碼塊中只有一條語句，也不應該省略大括號，如
|
if (null == $tab) { return ; // 雖然只有一條語句，也不應該省略{} } |
3.3.4運算符規範
原則：
（1） 賦值符號、比較符號兩側的變量應該在同一行，不要進行換行；
（2） 字符串使用單引號（’）要優於雙引號（”），尤其是在創建一個包含 HTML 代碼的字符串時；
3.4類、對象與原型鏈規範
原則：
（1） 使用 Array 和 Object 字面量語法, 而不使用 Array 和 Object 構造器（newArray()），避免因傳參不合適導致錯誤；
（2） 其命名規範參考第1節中命名規範；
編碼風格，建議如下：
1）比較長的標識符或者數值, 不要爲了讓代碼好看些而手工對齊. 如：
|
CORRECT_Object.prototype = { a: 0, b: 1, lengthyName: 2 }; |
不要這樣做: WRONG_Object.prototype = { a : 0, b : 1, lengthyName: 2 }; |
2）屬性名與屬性值之間不應該擁擠，應該在冒號“:”與屬性值之間空一格；
3.5錯誤處理
基本原則：
（1） 通常的法則是系統在正常狀態並且用戶正常操作下，不應產生任何異常。
（2） 對可預見的錯誤不進行捕捉。
（3） 對不可預見或者難以解決錯誤進行try{…}catch(e){..}捕捉處理。
3.5.1可預見錯誤
對可預見的錯誤不進行捕捉處理，而是在錯誤發生前通過條件判斷避免發生，如：
|
//若不對div1是否爲null進行檢查，則在其爲null時會拋出缺少對象錯誤 document.getElementById(“div1”).style.width = 100;
|
//預先對對象進行檢查 var objDiv1 = document.getElementById(“div1”); if(objDiv1!=null){ objDiv1.style.width = 100; } |
3.5.2不可預見錯誤
對不可預見或者因瀏覽器、腳本解析器BUG造成的難以解決的錯誤需要進行捕捉處理，如：
|
try{ xmlhttp.open(“GET”,url,NOT_ASYNC); }catch(e){ console.log(e.description); } |
【說明】：對捕捉到的錯誤一般情況必須給出反饋處理，例如console.log()，除非有必要提醒用戶，否則不應該使用alert()。
4 JavaScript其他規範
以下規範，除了說明爲建議、格式外，均爲必須遵循的原則：
（1） eval是惡魔。eval 是JavaScript中最容易被濫用的方法，避免使用它。
（2） 不要給setTimeout或者setInterval 傳遞字符串參數，應該使用函數參數。
（3） this僅在對象構造器, 方法, 閉包中使用。
this 的語義很特別。 有時它引用一個全局對象(大多數情況下)，調用者的作用域，DOM 樹中的節點(添加事件處理函數時)， 新創建的對象(使用一個構造器)，或者其他對象(如果函數被call()或apply())。使用時很容易出錯。
【說明】：在內嵌函數想要使用外層函數的調用者，必須將外層調用者賦值給一個變量，通常是self。
（4） 不要使用with(){}。
（5） 千萬不要修改內置對象, 如Object.prototype 和 Array.prototype 的原型；
（6） 使用 join() 來創建字符串。
|
通常是這樣使用的，但這樣在 IE 下非常慢: function listHtml(items) { var html = '<div class="foo">'; for (var i = 0, len = items.length; i < len; ++i) { if (i > 0) { html += ', '; } html += itemHtml(items[i]); } html += '</div>'; return html; } |
可以用下面的方式: function listHtml(items) { var html = []; for (var i = 0, len = items.length; i < len; ++i) { html[i] = itemHtml(items[i]); } return '<div class="foo">' + html.join(', ') + '</div>'; }
|
【說明】：即用數組作爲字符串構造器, 然後通過join('') 轉換成字符串。不過由於賦值操作快於數組的 push(), 所以儘量使用賦值操作.
【參考文獻】
[1] JavaScript編程規範. http://wenku.baidu.com/view/f3a4cde95ef7ba0d4a733b38.html
[2] Google JavaScript 編碼規範指南. http://wenku.baidu.com/view/3a045b66b84ae45c3b358c18.html?re=view
[3] js編碼規範. http://wenku.baidu.com/view/ccd97ba20029bd64783e2c0e.html
[4] javascript編程規範. http://wenku.baidu.com/view/b6e6a7d376eeaeaad1f3301e.html