JavaScript編碼規範

1. 目的

本規範的目的是使本組織能以標準的、規範的方式設計和編碼。經過創建編碼規範，以使每一個開發人員養成良好的編碼風格和習慣；並以此造成開發小組編碼約定，提升程序的可靠性、可讀性、可修改性、可維護性和一致性等，增進團隊間的交流，並保證軟件產品的質量。

 

2. 適用範圍

本規範適用於XXXXX有限公司技術部全部軟件開發人員，在整個軟件開發過程當中必須遵循此規範。

 

3. 版權聲明

²  本文檔爲共享文檔，不限轉載，但請保持本文檔的完整性

²  您能夠修改本文檔以符合您或組織、公司等之實際，但請在文檔中保持對本文檔的引用和說明。

²  未經產品開發中心受權，任何我的、組織或單位不得將本文檔用於書面發表、轉載、摘錄等，亦不得用於其餘商業行爲。

²  本人及本組織不承擔任何因使用、參考本文檔等而致使的任何可能責任或連帶責任。

 

4. 參考資料

²  《Sun Java語言編碼規範》(Java Code Conventions)

 

5. 概述

這是一套適用於JavaScript程序的編碼規範。它基於Sun的Java程序編碼規範。但進行了大幅度的修改, 由於JavaScript不是Java。

對於代碼，首要要求是它必須正確，可以按照設計預約功能去運行；第二是要求代碼必須清晰易懂，使本身和其餘的程序員可以很容易地理解代碼所執行的功能等。然而，在實際開發中，每一個程序員所寫的代碼卻常常自成一套，不多統一，致使理解困難，影響團隊的開發效率及系統的質量等。所以，一份完整並被嚴格執行的開發規範是很是必須的，特別是對軟件公司的開發團隊而言。

最根本的原則：

代碼雖然是給機器運行的，但倒是給人讀的！

運用常識。當找不到任何規則或指導方針，當規則明顯不能適用，當全部的方法都失效的時侯，運用常識並覈實這些基本原則。這條規則比其它全部規則都重要。常識是必不可少。

當出現該狀況時，應當及時收集並提交，以便對本規範進行修改。

 

6. 規範要求

 

6.1.  保證代碼壓縮後不出錯

對於大型的JavaScript項目，通常會在產品發佈時對項目包含的全部JavaScript文件進行壓縮處理，好比能夠利用Google Closure Compiler Service對代碼進行壓縮，新版jQuery已改用這一工具對代碼進行壓縮，這通常會去掉開發時寫的註釋，除去全部空格和換行，甚至能夠把原來較長的變量名替換成短且無心義的變量名，這樣作的目的是加快文件的下載速度，同時也減少網站訪問帶來的額外數據流量，另外在代碼保護上也起到了一點點做用，至少壓縮後的代碼即便被還原仍是沒那麼容易一下讀懂的。

要想代碼能正確經過壓縮，通常要求語句都要以分號正常結束，大括號也要嚴格結束等，具體還要看壓縮工具的要求。因此若是一開始沒有按標準來作，等壓縮出錯後再回去找錯誤那是浪費時間。

 

6.2.  保證代碼能經過特定IDE的自動格式化功能

通常較爲完善的開發工具（好比Aptana Studio）都有代碼「自動格式」化功能，這一功能幫助實現統一換行、縮進、空格等代碼編排，你能夠設置本身喜歡的格式標準，好比左大括號{是否另起一行。達到這個要求的目的在於方便你的開發團隊成員拿你代碼的一個副本用IDE自動格式化成他喜歡或熟悉的風格進行閱讀。你同事須要閱讀你的代碼，多是由於你寫的是通用方法，他在其它模塊開發過程當中也要使用到，閱讀你的代碼能最深刻了解方法調用和實現的細節，這是簡單API文檔不能達到的效果。

 

6.3.  使用標準的文檔註釋

這一要求算是最基本的，這有利於在方法調用處看到方法的具體傳參提示，也能夠利用配套文檔工具生成html或其它格式的開發文檔供其餘團隊成員閱讀，你能夠嘗試使用jsdoc-toolkit。若是你自動生成的API是出自一個開放平臺，就像facebook.com應用，那麼你的文檔是給天下全部開發者看的。

另外編寫完整註釋，也更方便團隊成員閱讀你的代碼，經過你的參數描述，團隊成員能夠很容易知道你編寫的方法傳參與實現細節。固然也方便往後代碼維護，這樣即便再大的項目，過了很長時間後，回去改點東西也就不至於本身都忘記了當時本身寫的代碼是怎麼一回事了。

 

6.4.  使用規範有意義的變量名

使用規範有意義的變量名能夠提升代碼的可讀性，做爲大項目開發成員，本身寫的代碼不只僅要讓別人容易看懂。開發大項目，其實每一個人寫的代碼量可能都比較大，規範命名，往後本身看回本身的代碼也顯的清晰易懂，好比往後系統升級或新增功能，修改起代碼來也輕鬆多了。若是到頭髮現本身當初寫的代碼如今看不太懂了，那還真是天大的笑話了。

固然，使用有意義的變量名也儘可能使用標準的命名，好比像這裏：var me = this也許沒有var self = this好，由於self是Python中的關鍵字，在Python中self就是一般語言this的用法。再看下面一個例子，加s顯然比沒有加來的科學些，這樣能夠知道這個變量名存的是複數，多是數組等：

var li = document.getElementsByTagName('li')  

var lis = document.getElementsByTagName('li') 

 

6.5.  不使用生偏語法

JavaScript做爲一門動態腳本語言，靈活性既是優勢也是缺點，衆所周知，動態語言不一樣層次開發人員對實現一樣一個功能寫出來的代碼在規範或語法上會存在較大的差異。無論怎麼樣，規範編碼少搞怪，不把簡單問題複雜化，不違反代碼易讀性原則纔是你們應該作的。

好比這語句：typeof(b) == 'string' && alert(b)應該改成：if (typeof(b) == 'string') alert(b)，像前面那種用法，利用了&&運算符解析機制：若是檢測到&&前語句返回false就再也不檢測後面語句，在代碼優化方面也有提到把最可能出現的狀況首先判斷，像這種寫法若是條件少還好，若是條件較多並且語句也長，那代碼可讀性就至關差。

又好比：+function(a){var p = a;}( 'a')應該改成：(function(a){var p = a;})( 'a')，其實function前面的+號與包含function的()括號做用是同樣的，都是起運算優先做用，後者是常見且容易看明白的防止變量污染的作法，好比好些流行JavaScript框架就是採用後面這種方式。

再說個下降代碼可讀性的例子，如：functiongetPostionTxt(type){return type == 2 ? "野外" : (type == 3 ? "商城" : (type == 4 ? "副本" : null));}應該改爲：function getPostionTxt(type){vartypeData={"2":"野外","3":"商城","4":"副本"};if (typeData[type]) return typeData[type]; else return null;}。若是type是從0開始不間斷的整數，那麼直接使用數組還更簡單，這種結果看起來就清晰多了，看到前面那種多層三元表達式嵌套頭不暈嗎。

 

6.6.  不在語句非賦值地方出現中文

語句中不該該出現中文我想通常人都知道，雖然這樣作不影響程序運行，可是顯然有背行業標準要求，固然咱們也不是在使用「易語言」作開發。關於這一個問題，我原本不想把它拿出來講的，但我確實遇到有人這樣作的，也不知道是否是由於他的英語實在太爛了，至少還能夠用拼音吧，另外尋求翻譯工具幫忙也不錯的選擇。我舉例以下，像如下寫法出如今教學中倒還能夠理解：

this.user['名字'] = '張三'　或者　this.user.名字 = '張三'

 

6.7.  明肯定義函數固定數量的參數

固定數量參數的函數內部不使用arguments去獲取參數，由於這樣，你定義的方法若是包含較多的腳本，就不能一眼看到這個方法接受些什麼參數以及參數的個數是多少。好比像下面：

var $ = function(){return document.getElementById(arguments[0]);}

應該改爲：

var $ = function(elemID){return document.getElementById(elemID);}

 

6.8.  沒必要熱衷動態事件綁定

雖然知道事件能夠動態綁定，好比使用addEventListener或者使用jQuery的bind方法，也知道採用動態事件綁定可讓XHTML更乾淨，可是通常狀況下我仍是建議直接把事件寫在DOM節點上，我認爲這樣可使代碼變得更容易維護，由於這樣作，咱們在查看源代碼的時候就能夠容易地知道什麼Element綁定了什麼方法，簡單說這樣更容易知道一個按鈕或連接點擊時調了什麼方法腳本。

 

6.9.  下降代碼與XHTML的耦合性

不要過於依賴DOM的一些內容特徵來調用不一樣的腳本代碼，而應該定義不一樣功能的方法，而後在DOM上調用，這樣無論DOM是按鈕仍是連接，方法的調用都是同樣的，好比像下面的實現顯然會存在問題：

function myBtnClick(obj)  

{  

if (/肯定/.test(obj.innerHTML))   

alert('OK');  

else if (/取消/.test(obj.innerHTML))   

alert('Cancel');  

else   

alert('Other');  

} 

<a herf="javascript:;" onclick="myBtnClick(this)">肯定</a>

<a herf="javascript:;" onclick="myBtnClick(this)">取消</a> 

上面例子其實在一個函數內處理了兩件事情，應該分紅兩個函數，像上面的寫法，若是把連接換成按鈕，好比改爲這樣：

<input type="button" onclick="myBtnClick(this)" value="肯定" />，

那麼myBtnClick函數內部的obj.innerHTML就出問題了，由於此時應該obj.value纔對，另外若是把按鈕名稱由中文改成英文也會出問題，因此這種作法問題太多了。

 

6.10. 一個函數應該返回統一的數據類型

由於JavaScrip是弱類型的，在編寫函數的時候有些人對於返回類型的處理顯得比較隨便，我以爲應該像強類型語言那樣返回，看看下面的兩個例子：

function getUserName(userID)  

{  

if (data[userID])  

return data[userID];  

else 

return false;  

} 

應該改成：

function getUserName(userID)  

{  

if (data[userID])  

return data[userID];  

else 

return "";  

} 

這個方法若是在C#中定義，咱們知道它準備返回的數據類型應該是字符串，因此若是沒有找到這個數據咱們就應該返回空的字符串，而不是返回布爾值或其它不合適的類型。這並無影響到函數未來的調用，由於返回的空字符串在邏輯判斷上可被認做「非」，即與false同樣，除非咱們使用全等於「===」或typeof進行判斷。

 

6.11. 規範定義JSON對象，補全雙引號

使用標準確定是有好處的，那麼爲何仍是有人不使用標準呢？我想這多是懶或習慣問題。也許還會有人跟我說，少寫引號能夠減輕文件體積，我認爲這有道理但不是重點。對於服務器返回的JSON數據，使用標準結構能夠利用Firefox瀏覽器的JSONView插件方便查看（像查看XML那樣樹形顯示），另外你若是使用jQuery作開發，最新版本jQuery1.4+是對JSON格式有更高要求的，具體的能夠本身查閱jQuery更新文檔。好比：{name:"Tom"}或{'name':'Tom'}都應該改爲{"name":"Tom"}。

 

6.12. 不在文件中留下將來肯定再也不使用的代碼片斷

當代碼調整或重構後，以前編寫的再也不使用的代碼應該及時刪除，若是認爲這些代碼還有必定利用價值能夠把它們剪切到臨時文件中。留在項目中不只增長了文件體積，這對團隊其它成員甚至本身都起到必定干擾做用，怕未來本身看回代碼都搞不懂這方法是幹什麼的，是否有使用過。固然能夠用文檔註釋標籤@deprecated把這個方法標識爲不推薦的。

 

6.13. 不重複定義其餘團隊成員已經實現的方法

對於大型項目，通常會有部分開發成員實現一些通用方法，而另一些開發成員則要去熟悉這些通用方法，而後在本身編寫模塊遇到有調用的須要就直接調用，而不是像有些開發者喜歡「單幹」，根本不會閱讀這些通用方法文檔，在本身代碼中又寫了一遍實現，這不只產生多餘的代碼量，固然也是會影響團隊開發效率的，這是沒有團隊合做精神的表現，是重複造輪子的悲劇。

好比在通用類文件Common.js有定義function $(elemID){return document.getElementById(elemID)}那麼就不該該在Mail.js中再次出現這一功能函數的重複定義，對於一些複雜的方法更應該如此。

 

6.14. 調用合適的方法

當有幾個方法均可以實現同類功能的時候，咱們仍是要根據場景選擇使用最合適的方法。下面拿jQuery框架的兩個AJAX方法來講明。若是肯定服務器返回的數據是JSON應該直接使用$.getJSON，而不是使用$.get獲得數據再用eval函數轉成JSON對象。若是由於本次請求要傳輸大量的數據而不得以使用$.post也應該採用指定返回數據類型（設置dataType參數）的作法。若是使用$.getJSON，在代碼中咱們一眼能看出本次請求服務器返回的是JSON。

舒適提示：jQuery1.4後，若是服務器有設置數據輸出的ContentType，好比ASP.NET C#設置 Response.ContentType = "application/json"，那麼$.get將與$.getJSON的使用沒有什麼區別。

 

6.15. 使用合適的控件存儲合適的數據

曾發現有人利用DIV來保存JSON數據，以待頁面下載後未來使用，像這樣：<div id="json">{ "name":"Tom"}</div>，顯然這個DIV不是用來界面顯示的，若是非要這樣作，達到使用HTML文件進行數據緩存的做用，至少改爲用隱藏域來存這數據更合理，好比改爲：<input type="hidden" value=" { "name":"Tom"}" />。

其實也能夠利用window對象來保存一些數據，像上面的例子，咱們能夠在AJAX請求頁直接包含這樣的腳本塊：<script>window.userData = { "name":"Tom"};</script>，當在AJAX請求回調函數中執行完$( "#MyDiv ").html(data)後，在window上就立刻有了這一變量。若是採用第一種方法，將不可避免eval(document.getElementById("UserData").innerHTML)。若是在window對象存放大量數據的話，這些數據不用時要及時手動清理它們，它們是要等瀏覽器刷新或重啓後纔會消失的，這就會增長內存開銷。

 

6.16. 重視代碼優化工做

代碼最優化是每一個程序員應該努力達到的目標，也應該成爲程序員永遠的追求。寫代碼的時候，不該該急着把功能實現出來，要想一下如何寫代碼，代碼的執行效率纔是較好的。

舉個例子：假設有定義getElementById的快捷方法functoin $(elemID){return document.getElementById(elemID)}，那麼有人可能會寫出這樣的代碼$("MyDiv").parentNode.removeChild($("MyDiv"))，其實這裏執行了兩次getElementById DOM查找，若是改爲這樣將更好：varmyDiv = $("MyDiv"); myDiv.parentNode.removeChild(myDiv)。還好getElementById的DOM查找算比較快，若是換成getElementsByTagName則更應該注重優化了。jQuery開發團隊也有提醒你們要注意這方面的問題。

固然，代碼優化技巧也是須要我的不斷積累的。曾有朋友跟我說他寫網站後臺代碼歷來不用考慮優化的，由於他們網站用的是至強四核服務器，我以爲這是很好笑的。

 

6.17. 能用面向對象方法進行接口定義和代碼組織

這一能力對於每個程序員來講都是很是重要的，這也是決定一個程序員水平高低的一個重要因素。可以把需求細化並抽象出不一樣的類，而後有條理地編寫代碼，使代碼結構清晰，可讀性高，代碼易於維護，不至於太過程化並且雜亂無章，這樣纔算是一個優秀的程序員。