網易前端JavaScript編碼規範

總所周知，javascript是一種文法極其靈活的語言。javascript在設計之初就只是用來為HTML添加動態效果的。由於他動態，弱類型等特性，以及不同瀏覽器的相容性問題，造成了開發成本要比java等語言要高很多。正因為它太靈活，我們制定了適用於網易郵箱的javascript編碼規範，儘可能多的降低由於文法靈活造成的問題。以下將具體介紹：

　　1. 變數命名規範

　　變數名包括全域變數，局部變數，類變數，函數參數等等，他們都屬於這一類。

　　基本規範

　　變數命名都以類型首碼+有意義的單片語成，單詞首字母都需要大寫。例如：sUserName，nCount。

　　首碼規範

　　每個局部變數都需要有一個類型首碼，按照類型可以分為：

　　s：表示字串。例如：sName，sHtml;

　　n：表示數字。例如：nPage，nTotal;

　　b：表示邏輯。例如：bChecked，bHasLogin;

　　a：表示數組。例如：aList，aGroup;

　　r：表示Regex。例如：rDomain，rEmail;

　　f：表示函數。例如：fGetHtml，fInit;

　　o：表示以上未涉及到的其他對象，例如：oButton，oDate;

　　例外情況：

　　1：範圍不大臨時變數可以簡寫，比如：str，num，bol，obj，fun，arr。

　　2：迴圈變數可以簡寫，比如：i，j，k等。

　　為什麼需要這樣強制定義變數首碼?正式因為javascript是弱語言造成的。在定義大量變數的時候，我們需要很明確的知道當前變數是什麼屬性，如果只通過普通單詞，是很難區分的。

 

　　例如：

var group = []; 
group.name = 'myGroup'; 
/**** 
some code 
***/
//這時候你還能一眼就看出來group是什麼嗎？

 

　　又例如：

var checked = false; 
var check = function(){ 
    return true; 
} 
/** 
some code 
**/
if(check){//可能將checked寫成check，由於不能很快速的發現check是函數，造成邏輯錯誤 
    //do some thing 
}

 

　　如果我們寫成：

var bChecked = false; 
var fCheck = function(){ 
    return true; 
} 
/** 
some code 
**/
if(bChecked){ 
    // do some thing 
} 
if(fCheck()){ 
    // do other thing 
}

 

　　就清楚很多了。

　　全域變數以及常量規範

　　網易郵箱前端是基於“類”的概念來來開發javascript的(稍後會專門介紹)，每個類定義都是在一個閉包函數中，除了在window下有類的定義而外，只允許有兩種變數定義在全域，那就是全域變數和常量。

　　全域變數使用g作為首碼，定義在window下。例如gUserName，gLoginTime。

　　某些作為不允許修改值的變數認為是常量，全部字母都大寫。例如：COPYRIGHT，PI。常量可以存在於函數中，也可以存在於全域。

　　看個例子就 很容易明白為什麼要這樣定義了：

var userName = "dongua"; 
function checkName(userName){ 
    //存在函數參數userName以及全域變數userName,如果要比較兩個值是否相等，必需寫為 
    return window.userName == userName 
}

 

　　如果使用了全域變數的首碼，就十分清晰了。

　　2. 函數命名規範

　　統一使用動詞或者動詞[+名詞]形式，例如：fGetVersion()，fSubmitForm()，fInit();涉及返回邏輯值的函數可以使用is，has等表示邏輯的詞語代替動詞。

　　如果有內建函式，使用__f+動詞[+名詞]形式，內建函式必需在函數最後定義。例如：

function fGetNumber(nTotal){ 
    if(nTotal<100){ 
  nTotal = 100; 
   } 
return __fAdd(nTotal);   
  
function __fAdd(nNumber){ 
  nNumber++; 
  return nNumber; 
} 
} 
alert(fGetNumber(30));//alert 101

 

　　對象方法實現

　　對象方法命名使用 f+對象類名+動詞[+名詞]形式;例如 fAddressGetEmail

　　事件響應函數

　　某事件響應函數命名方式為觸發事件對象名+事件名或者模組名+觸發事件對象名+事件名，例如：fDivClick()，fAddressSubmitButtonClick()

　　3.其他注意事項

　　1：所有命名最好使用英語表示。

　　2：所有變數名應該明確而必要，盡量避免不必要的容易混淆的縮寫。

　　3：netease.events.mouse.Handler，而不是 netease.events.mouse.MouseEventHandler。

　　4：對應的方法應該使用對應的動詞，例如：get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end。

　　5：應該避免雙重否定意義的變數，例如：bIsNotError, bIsNotFound，不可取。

　　6：變數應該在最小的範圍內定義，並儘可能的保持最少的啟用時間。

　　7：迴圈變數最好在迴圈中定義。例如for(var i=0,m=10;i

　　8：盡量避免複雜的條件陳述式，可以使用臨時的boolean變數代替。

　　9：一定要避免在條件中執行語句，例如：if((i=3)>2){}，不可取。

　　10：不要在代碼中重複使用相同意義的數字，用一個變數代替，比如 nTotal=100; num= total。

 

　　網易郵箱頁面在window只允許定義三種變數——1：全域變數;2：常量;3：類。任何商務邏輯都需要通過類方法或者樣本方法實現。前兩種變數在之前文章中已經介紹，在此不再累述，接下來詳細介紹類定義和使用的規範。

　　定義類是通過一個閉包完成的：

(function(){ 
  //第一步：引入存在的類。引入support類 
  var Support = window.Support;  
  
  //$是網易郵箱基礎庫“base”的引用稍後會介紹 
  //第二步：定義類。可以認為返回了一個類定義 function(){}，並在window下定義一個Image類 
  var Image = $.createClass("Image");  
  
  //可以認為是jQuery的extend方法  
  
  //第三步：定義類屬性/方法定義 
  $.Object.extend(Image,{ 
   _language : null,   //內部屬性 
   getSize  : fImageGetSize 
  }); 
  //第四步：定義執行個體屬性/方法定義 
  $.Object.extend(Image.prototype,{ 
   name  : null, 
   url   : null, 
   ext   : null, 
   width  : 0, 
   height  : 0, 
   setName  : fImageSetName, 
   getName  : fImageGetName, 
   init  : fImageInit 
  }); 
  //第五步：方法實現  
  
  function fImageGetSize(nWidth,nHeight){ 
   return nWidth*nHeight; 
  }  
  
  function fImageSetName(sName){ 
   var oImage = this; 
   oImage.name = sName; 
  }  
  
  function fImageGetName(){ 
   var oImage = this; 
   return oImage.name; 
  }  
  
  function fImageInit(sUrl){ 
   var oImage = this; 
   oImage.url = sUrl; 
   oImage.ext = Support.getExt(sUrl); 
   oImage.width = Support.getWidth(sUrl); 
   oImage.height = Support.getHeight(sUrl); 
  }  
  
})();

 

　　我們可以看到，這個閉包完成了以下幾件事情：

　　1.引入這個類需要用到的其他類。

　　2.定義這個類。

　　3.定義類的屬性和方法。

　　4.定義類的執行個體屬性和方法。

　　5.類和執行個體方法的實現。

　　在命名上，我們遵循了一下規則：

　　1.類名首個字母必需大寫，例如Image，Support等。

　　2.屬性名稱需要是有意義的名詞，首字母小寫，例如oImage.width。

　　3.方法名需要是有意義的動詞[+名詞]，首字母小寫，例如Support.getWidth

　　4.如果不希望被其他方法調用，需要在屬性或者方法名前面加“_”，例如oImage._language

　　5.如果不希望被子類調用，需要在屬性或者方法名前加“_”，例如oImage.__fire()

　　這裡需要特別說明以下幾點：

　　1.方法的定義不是通過匿名函數來定義，而是集中在類定義的下面來實現。這樣的好處是能在最開始將類的屬性方法定義都羅列出來，便於通過源碼查看到對應屬性和方法。

　　2.在類/執行個體方法中，使用局部變數代替this。this不是一個好的玩意兒，一不小心就會被this搞暈。使用局部變數能夠盡量避免這樣的問題，也能夠在壓縮混淆的時候效果更好。

　　3.在實際開發過程中，每個類定義都單獨一個js實現。

　　除了類的定義，閉包不實現 任何其他邏輯。使用閉包能夠將很多變數約束在閉包範圍中，並且能夠在壓縮混淆中效果更好.

作者：zdrjlamp