JavaScript編碼規(guī)范

JavaScriptJavaScript 編碼規(guī)范編碼規(guī)范 20162016 年年 0202 月月 1818 日日 第 1 頁 規(guī)范基本信息表 規(guī)范簡稱 JavaScript編碼規(guī)范 規(guī)范版本號 1 0 規(guī)范修訂日期 2016 02 18 本規(guī)范位置 先前版本位置 規(guī)范制定組織 規(guī)范制定牽頭人 王軍鋒 規(guī)范校訂人 第 2 頁 JavaScript 編碼規(guī)范 1 概要 1 1 規(guī)范摘要 本規(guī)范主要目的是定義基于JavaScript編碼的總體規(guī)范 確保編碼的規(guī)范性 提高程序的可維護性 通過遵循共同的編碼規(guī)范 程序開發(fā)人員可以保持代碼一貫的風(fēng)格 提高代碼編寫的可讀性和使用的一貫 性 1 2 背景 1 3 現(xiàn)狀 1 4 相關(guān)工作說明 1 5 規(guī)范聲明 2 適用范圍 3 引言 3 1 詞匯表 3 1 1 首選術(shù)語 3 1 2 相關(guān)術(shù)語 3 2 格式約定 3 3 文件引用 ECMAScript 262標(biāo)準(zhǔn) 第 3 頁 JavaScript權(quán)威指南V5 JavaScript高級程序設(shè)計V2 JavaScript高性能 Google JavaScript開發(fā)規(guī)范 4 需求 5 規(guī)范正文 5 1 排版規(guī)范 5 1 1 文件結(jié)構(gòu) JavaScript文件按如下順序組織各元素 序號元素說明 1 版權(quán) 版本聲明以注釋的方式進行聲明 2 總體注釋在注釋中總體介紹該文件實現(xiàn)的功能 對如何使用這些功能給出指導(dǎo)性意見 給出使用示例 指出注意事項 羅列依賴的其它JavaScript文件 注明 第一作者 第二作者 3 程序內(nèi)容 5 1 2 縮進排版 以4個空格為一個縮進單元 避免使用Tab制表符 示例 function getUser id if id throw new Error 5 1 3 行排版 一行的字符不建議超過120個字符 一行過多的字符會影響查看程序的效率 如果一段描述不能放在一行中 依據(jù)下列規(guī)則將其拆分成多行 1 從分隔符 比如空格 后換行 2 在運算符之前換行 第 4 頁 3 不拆分完整的單詞 4 換行后如果需要縮進則不應(yīng)縮進超過行中 示例 if condition1 function setUser user this user user 代碼邏輯段之間空一行 示例 function getUser id 判斷參數(shù)id的合法性 if id throw new Error 根據(jù)參數(shù)id查找user對象 findUser id 5 1 5 語句 5 1 5 1 表達式語句 表達式語句以分號結(jié)束 示例 var i 0 alert 提示信息 Math cos x 5 1 5 2 復(fù)合語句 第 5 頁 復(fù)合語句是包含在花括號中的一個語句或者語句塊 復(fù)合語句遵循如下排版規(guī)則 1 左花括號 位于復(fù)合語句起始行的行尾 右大括號 應(yīng)另起一行并與復(fù)合語句首行對齊 2 花括號中的語句縮進一個層次 4 個空格 返回語句 示例 var x 0 5 1 5 3 if else 語句 if else 語句總是用 和 括起來 避免發(fā)生錯誤 示例 if expression1 statement1 else if expression2 statement2 else statement3 5 1 5 4 for 語句 示例 for initialize test increment statement 一個空的for語句 在初始化 條件判斷 更新子句中完成 應(yīng)該具有如下格式 示例 for initialize test increment 5 1 5 5 for in 語句 示例 for variable in object statement 5 1 5 6 while 語句 示例 while expression statement 5 1 5 7 do while 語句 示例 do statement 第 6 頁 while expression 5 1 5 8 switch 語句 示例 switch expression case value1 statement break case value2 statement break default statement break 當(dāng)一個執(zhí)行完一個case后需要順著往下執(zhí)行 即沒有break語句 時 通常應(yīng)在break語句的位置添加 注釋 上面的示例代碼中就包含注釋 5 1 5 9 try catch finally 語句 示例 try statement catch e statement finally statement 5 2 注釋規(guī)范 5 2 1 注釋位置 1 函數(shù)和方法 每個函數(shù)和方法都應(yīng)該包含一個注釋 描述其目的和用于完成任務(wù)所可能使用的算 法 基于參數(shù)類型 參數(shù)可選擇值 返回值 2 大段代碼 用于完成單個任務(wù)的多行代碼應(yīng)該在前面填加描述任務(wù)的注釋 3 復(fù)雜的算法 在使用復(fù)雜算法的代碼處添加注釋 以便下次查閱代碼時幫助理解 4 Hack 因為不同的瀏覽器存在差異 JavaScript以便會包含一些hack 需要在這些hack的代碼前 添加注釋 以便提醒代碼維護者 5 2 2 塊注釋 塊注釋以 開頭或者 開頭 以 結(jié)尾 Doc注釋以 開頭 比如 注釋在JavaScript文 件開頭 函數(shù) 變量上的注釋通常會用于生成doc文檔 非Doc注釋的多行注釋以 開頭 第 7 頁 在Doc注釋中需要注明類型 常見的類型包括 Object Array Function Number String Boolean Math等 類型注釋規(guī)則如下表 符號舉例說明 類型 Object 對象類型 Number Object Number或者Object類型 Object 非對象類型 未知類型 所有類型 注 在注釋中的Number包裝類型代指Number類型或者number基本類型 其它包裝類型類似 Doc注釋舉例 示例 Object 用戶對象 var user 通過用戶對象獲取用戶名稱 param Object user 用戶對象 return String 用戶名稱 function getUserName user 如果 user 為 null 則該方法會出現(xiàn)異常 需要對輸入?yún)?shù) user 進行可靠性校驗 需判斷 user 變量是否是 user 對象 return user name 如果沒有返回值 可以不用在注釋中寫 return 設(shè)置用戶名稱 param Number age 用戶名稱 function setUserName name this name name 5 2 3 單行注釋 單行注釋 以 開頭 非Doc注釋時使用 示例 第 8 頁 function getUserName user 返回用戶名稱 return user name 5 2 4 JavaScript 文件注釋 在文件頭位置對JavaScript文件進行注釋 說明該文件的版權(quán) 版本等信息 示例 本文件是 項目名稱 V VERSION的一部分 Copyright C 2000 2011 公司名稱 Provider 組織名稱 聯(lián)系方式 版權(quán)說明 5 2 5 函數(shù) 方法注釋 示例 通過用戶對象獲取用戶名稱 param Object user 用戶對象 return String 用戶名稱 function getUserName user return user name 5 2 6 變量 屬性注釋 示例 Object 用戶對象 var user 5 3 聲明規(guī)范 5 3 1 變量 局部變量和全局變量均使用var關(guān)鍵字進行聲明 示例 var name 第 9 頁 在同一作用域 在JavaScript中共三種作用域 全局作用域 局部作用域 嵌套局部作用域 的開頭 位置聲明變量 避免出現(xiàn)重復(fù)聲明變量的問題 for for in語句的循環(huán)變量除外 示例 全局變量全局變量 var globalV global function printUserProperty 局部變量局部變量 var users name 用戶1 name 用戶2 for for語句變量語句變量i i useruser for var i 0 user user users i i printUserProperty user function printUserProperty user 嵌套局部變量嵌套局部變量 var count 10 for in for in語句變量語句變量propprop for var prop in user alert prop 聲明全局變量 對象屬性 函數(shù)參數(shù)時需注釋變量類型或者賦初值 通過初值確定變量類型 由于局 部變量是在代碼塊內(nèi)部定義 作用范圍有限 因此不做要求 示例 全局變量全局變量 var isSuccess false 推薦的布爾類型初始值 推薦的布爾類型初始值 falsefalse var count 1 推薦的推薦的numbernumber類型初始值 類型初始值 1 1 var name 推薦的字符串類型初始值 推薦的字符串類型初始值 var user null 推薦的對象類型初始值 推薦的對象類型初始值 nullnull var obj 對象屬性對象屬性 name 函數(shù)參數(shù)函數(shù)參數(shù) 設(shè)置名稱 param param string string namename 名稱名稱 return 第 10 頁 function setName name 可以一次聲明多個變量 變量之間用 分隔 如果變量有初值或者注釋則需換行 換行后與上一 行的第一個變量左對齊 示例 var name password age sex 有注釋或者初值應(yīng)換行有注釋或者初值應(yīng)換行 var name password age 年齡 sex 男 采用直接量的方式聲明對象 提高對象聲明的代碼可讀性 對象屬性和方法行前空4格 對象的屬性或 者方法以 分隔 最后一個屬性或者方法不應(yīng)出現(xiàn) 屬性之間不空行 方法之間空兩行 示例 優(yōu)優(yōu) var user id name setName function name this name name getName function return this name 劣劣 var user new Object user id user name user setName function name this name name user getName function return this name 采用直接量的方式聲明數(shù)組 盡量不采用構(gòu)造函數(shù) 避免錯誤 示例 第 11 頁 優(yōu)優(yōu) var arr x1 劣劣 如果如果x1x1是正整數(shù) 則數(shù)組長度是正整數(shù) 則數(shù)組長度 x1 x1 如果如果x1x1是非正整數(shù)的是非正整數(shù)的numbernumber 則會出現(xiàn) 則會出現(xiàn)errorerror 如果如果x1x1是非是非numbernumber類型 數(shù)組長度類型 數(shù)組長度 1 x1 1 x1將作為數(shù)組的一個內(nèi)容將作為數(shù)組的一個內(nèi)容 var arr new Array x1 5 3 2 函數(shù) 使用function關(guān)鍵字聲明函數(shù) 示例 function getUser 函數(shù)變量 var getUser function 函數(shù)參數(shù)之間用 分隔 示例 function createUser id name password 函數(shù)代碼行前空4格 示例 function getUser return name 用戶 相鄰函數(shù)之間空2行 示例 function setUser function setUser user 匿名函數(shù)的右花括號右端不應(yīng)有代碼 左花括號左端不應(yīng)有代碼 示例 excute whatever function p1 p2 第 12 頁 在 function的根下聲明函數(shù) 避免在if等語句塊下聲明函數(shù) 以符合ECMAScript 262標(biāo)準(zhǔn) 示例 劣 劣 if x function foo 替代方案 使用函數(shù)變量替代方案 使用函數(shù)變量 if x var foo function 5 4 命名規(guī)范 5 4 1 文件 當(dāng)在一個project中引入其它JavaScript文件時 會存在文件名稱相同的可能 因此需要采取一定的 措施減少重名的可能性 推薦的方式 js 文件名稱全部小寫 示例 epri sotower ui grid js 5 4 2 命名空間 在JavaScript中 通過對象的屬性模擬命名空間 避免變量 函數(shù)重名 推薦的命名規(guī)則與文件命名 基本一致 示例 在epri sotower ui grid js文件中為Grid對象定義一個方法createGrid var epri epri if typeof epri object throw new Error 命名空間epri已經(jīng)存在但是不是對象 epri sotower epri sotower if typeof epri sotower object throw new Error 命名空間epri sotower已經(jīng)存在但是不是對象 epri sotower ui epri sotower ui if typeof epri sotower ui object throw new Error 命名空間epri sotower ui已經(jīng)存在但是不是對象 if epri sotower ui Grid throw new Error epri sotower ui Grid已經(jīng)存在 第 13 頁 sotower ui Grid createGrid function 執(zhí)行Grid類的createGrid方法 epri sotower ui Grid createGrid 5 4 3 構(gòu)造函數(shù) 類 構(gòu)造函數(shù)是指 初始化一個對象的屬性并且專門和new運算符一起使用的函數(shù) 通常采用構(gòu)造函數(shù)實 現(xiàn)類的概念 構(gòu)造函數(shù)采用首字母大寫的駝峰式命名 示例 function User id name password this id id this name name this password password var user new User id1 用戶 111111 alert user name 5 4 4 變量 對象屬性 在本小節(jié)變量代指 變量 對象屬性 變量由字母 數(shù)字或下劃線組成 變量的第一個字符不能是數(shù)字 變量的名稱不能是JavaScript保留 字 參考附錄1 示例 正確正確 var user null var user null var user1 null 錯誤錯誤 var 1user null var user null 變量采用首字母小寫的駝峰式命名 示例 var userName var user userName 第 14 頁 變量名稱應(yīng)具有一定的含義 示例 優(yōu)優(yōu) var userName 劣劣 var aa 在JavaScript中沒有私有變量的語法 但是可以通過注釋或者為變量增加 前綴等方式表示為私有變 量 通常采用加 前綴的方式 示例 var user 私有變量私有變量 roles getRoles function return this roles 5 4 5 常量 在JavaScript中沒有常量的語法 但是可以采取特殊的命名方式把一個變量表示為常量 所有字母大 寫 單詞之間用 鏈接 示例 var MAX WIDTH 1024 5 4 6 函數(shù) 對象方法 對象方法是作為對象屬性的函數(shù) 因此在本小節(jié)中函數(shù)代指 函數(shù) 對象方法 函數(shù)名稱由字母 數(shù)字或下劃線組成 第一個字符不能是數(shù)字 函數(shù)名稱不能是JavaScript保留字 參考附錄1 示例 正確正確 function getUser function getUser2 錯誤錯誤 function 1getUser function get setName function name this name name isBoy function return this sex 男 第 16 頁 5 4 7 事件 處理事件的函數(shù)名稱以 Handler 后綴結(jié)尾 在名稱中需要包含事件的類型和代表觸發(fā)事件的HTML 元素的名稱 示例 在頁面中有一個輸入用戶名稱的input框 則處理它的onchange事件的函數(shù)命名如下 function userNameInputChangeHandler e 5 5 編碼健壯性遵循原則 5 5 1 合理使用閉包 閉包容易導(dǎo)致內(nèi)存泄露 尤其是使用閉包函數(shù)處理DOM事件時經(jīng)常會出現(xiàn)HTML元素與閉包函數(shù)的相互 引用 從而導(dǎo)致無法釋放HTML元素和閉包函數(shù)的內(nèi)存 示例 劣劣 在執(zhí)行完foo方法后 局部變量element不會被垃圾回收 因為它的閉包函數(shù)被注冊到element元素的單擊 事件中 被element引用 而閉包函數(shù)又持有foo函數(shù)內(nèi)的所有變量包括element 如此形成element和foo 內(nèi)的閉包函數(shù)的循環(huán)引用 從而element和foo均不能被垃圾回收 導(dǎo)致內(nèi)存泄露 function foo element a b element onclick function 使用變量a b 優(yōu)優(yōu) 改造后的正確用法如下 element會引用函數(shù)bar返回的函數(shù) 不會引用到foo 避免了循環(huán)引用 從而執(zhí)行完foo方法后 element 將被垃圾回收 function foo element a b element onclick bar a b function bar a b return function 使用a b 5 5 2 合理使用 for 和 for in 循環(huán) 使用普通的for語句循環(huán)數(shù)組 使用for in語句循環(huán)對象 不建議使用for in語句循環(huán)數(shù)組 因為如 果使用for in循環(huán)數(shù)組在一些使用場景下會導(dǎo)致問題 示例 劣劣 function printArray arr 第 17 頁 for var key in arr alert arr key printArray 0 1 2 3 可以alert出正確的結(jié)果 var a new Array 10 printArray a 錯誤 沒有alert a document getElementsByTagName printArray a 錯誤 會alert出a的length值 a 0 1 2 3 a buhu wine printArray a 錯誤 會alert出wine a new Array a 3 3 printArray a 錯誤 只alert一次 優(yōu)優(yōu) 把以上示例的把以上示例的for infor in語句改造成普通的語句改造成普通的forfor語句 則不存在以上問題語句 則不存在以上問題 function printArray arr var l arr length for var i 0 i l i alert arr i 只在循環(huán)對象時使用for in 示例 for var p in user alert p 注意添加到對象的prototype中的成員將被包含在遍歷中 可以通過使用hasOwnProperty方法來區(qū)分是否 對象自有屬性或者方法 5 5 3 避免無限循環(huán) 1 在使用for等循環(huán)語句進行循環(huán)時 要確保終止循環(huán)的條件一定能被觸發(fā) 避免無限循環(huán) 2 避免函數(shù)之間相互調(diào)用 形成隱式無限循環(huán) 示例 錯誤錯誤 function f1 f2 第 18 頁 function f2 f1 f1 5 5 4 區(qū)分 和 是完全等于 即除了值必須相等外 類型也必須相等 示例 var v1 1 var v2 1 alert v1 v2 true alert v1 v2 false 5 5 5 字符串拼接 使用 進行字符串多行拼接 不建議使用 因為MCMAScript標(biāo)準(zhǔn)不支持 拼接方式 并 且 拼接方式會導(dǎo)致行前的空白被包含在變量中 示例 劣劣 var myString A rather long string of English text an error message actually that just keeps going and going an error just gravy Have a nice day 優(yōu)優(yōu) var myString A rather long string of English text an error message actually that just keeps going and going an error just gravy Have a nice day 5 5 6 避免在函數(shù)中定義全局變量 示例 劣劣 function doSomething user 不使用var關(guān)鍵字會定義一個全局的user變量 5 5 7 避免在 JavaScript 中包含過多的 HTML CSS 內(nèi)容 在JavaScript中盡量少包含CSS樣式 HTML的內(nèi)容 如果必須使用CSS 盡量把樣式寫入CSS文件 在 JavaScript中對class進行操作 如果必須使用HTML 且HTML內(nèi)容比較多 則應(yīng)該把HTML相關(guān)內(nèi)容歸集到 一個文件中 并根據(jù)需要使用模板技術(shù) 5 5 8 異常處理 1 把可能出現(xiàn)錯誤的程序塊放入try語句中 把處理錯誤的代碼放到catch或者finally語句中 2 ECMAScript只為Error對象定義了兩個屬性 一個是保存錯誤信息的message屬性 一個是保存錯誤類 型的name屬性 ECMAScript共定義了7中錯誤類型 其中Error是基本錯誤類型 但是IE FireFox 等瀏覽器通常會為Error添加自有的屬性 因此如果應(yīng)用需要支持跨瀏覽器 只使用message name屬 性 第 19 頁 3 在finally子句中使用return語句時 return的應(yīng)該是一個變量 示例 劣劣 try return 2 catch e finally return 1 最終返回的永遠是1 優(yōu)優(yōu) var rv 1 try rv 2 catch e rv 1 finally return rv 如果沒有錯誤則返回2 有錯誤則返回1 4 使用throw關(guān)鍵字拋出異常 throw的應(yīng)該是Error或者Error的子對象 示例 劣劣 throw 優(yōu)優(yōu) throw new Error msg new一個Error或者Error的子對象 5 在可以的情況下 盡量使用throw拋出自己的異常信息 避免出現(xiàn)錯誤時 顯示的是瀏覽器默認(rèn)的錯 誤信息 不利于排錯 尤其是生產(chǎn)環(huán)境下 有較好的自定義錯誤信息 將對排錯提供很好的幫助 示例 優(yōu)優(yōu) function process values if values throw new Error xx js process 參數(shù)values 必須有值 6 只處理可以處理的錯誤 7 通過原型prototype繼承Error類 實現(xiàn)自定義錯誤類型 示例 function SelfError message this name SelfError this message message SelfError prototype new Error 8 記錄JavaScript錯誤到服務(wù)器端 以便分析錯誤 示例 第 20 頁 通過Image元素記錄錯誤到服務(wù)器端 param String level 錯誤級別 可選值 debug info warn erorr param String msg 錯誤信息 function logError level msg var img new Image img src context log so level encodeURIComponent level for var i 0 i 100 i try Code catch error logError info 處理 時發(fā)生錯誤 錯誤時的狀態(tài)是 5 6 性能優(yōu)化 5 6 1 合理使用 prototype 在使用prototype實現(xiàn)繼承時 不應(yīng)層級太多 否則會影響到在子類中使用父類方法時的性能 5 6 2 本地緩存對象屬性 在多次使用對象屬性的程序塊中 應(yīng)該為屬性定義本地變量 在后續(xù)程序只使用本地變量 這樣可以 減少JavaScript引擎在對象中查找屬性的次數(shù) 提高訪問性能 在循環(huán)中使用引用時尤其有效 示例 var obj name var name obj name var obj2 for var i 0 i 100 i obj2 name name i 5 6 3 減少操作 HTML DOM 結(jié)構(gòu)的次數(shù) 盡量減少JavaScript操作DOM的次數(shù) 在對DOM進行新增 替換節(jié)點時 可以先把相應(yīng)的內(nèi)容準(zhǔn)備好后 通過innerHTML方式一次完成對DOM的操作 5 6 4 減少在 HTML 中嵌入過多 JavaScript 代碼 盡量減少在HTML文件中嵌入的JavaScript代碼 把JavaScript代碼歸集到JavaScript文件中 可以借 助JavaScript編譯工具進行優(yōu)化和壓縮 從而減小網(wǎng)絡(luò)流量 5 6 5 引用 JavaScript 文件 第 21 頁 標(biāo)簽可以放在body的最后 以便減少由于加載script文件而導(dǎo)致其它頁 面組件的延遲顯示的問題 5 6 6 壓縮 JavaScript 文件 使用Google Compiler壓縮JavaScript文件 在項目中只使用壓縮后的JavaScript文件 提高 JavaScript文件加載速度 5 6 7 事件代理 在為HTML添加較多事件函數(shù)時 建議采用事件代理機制 在父節(jié)點代理所有子節(jié)點進行事件處理 避 免瀏覽器為子節(jié)點注冊事件 在子節(jié)點比較多時 比如 為表格的每個單元格注冊事件處理器時采用機制 代理機制對性能改善尤為明顯 6 一致性約束 6 1 引言 本文檔主要是規(guī)范實現(xiàn)過程中的編碼實現(xiàn) 以保證JavaScript編碼的統(tǒng)一 增加可讀性 可維護性 6 2 一致性考查表 此表用于描述在前述規(guī)范中提到的各項規(guī)范的約束等級 分為強制和推薦兩級 任何強制性約束沒有 滿足時 處于未遵守此規(guī)范的狀況 滿足所有強制性約束 但未實現(xiàn)部分或全部推薦性約束時 處于遵守 此規(guī)范的狀況 全部實現(xiàn)所有強制性和推薦性約束時 處于完全符合此規(guī)范的狀況 規(guī)范點標(biāo)記規(guī)范點說明約束等級 強制 M 推薦 O 5 1排版規(guī)范M 5 2注釋M 5 3聲明規(guī)范M 5 4命名規(guī)范M 5 5編碼健壯性遵循原則M 5 6性能優(yōu)化M 5 6 1合理使用 prototypeO 5 6 2本地緩存對象屬性O(shè) 5 6 3減少操作 HTML DOM 結(jié)構(gòu)的次 數(shù) M 5 6 4減少在 HTML 中嵌入過多 JavaScript 代碼 O 5 6 5引用 JavaScript 文件O 5 6 6壓縮 JavaScript 文件M 5 6 7事件代理O 7 附錄 7 1 保留字 第 22 頁 正在使用的保留字 breakdeletefunctionreturntypeof casedoifswitchvar catchelseinthisvoid