在打造郵箱 Webmail 產品的漫長歷程中,網易郵箱前端團隊沉澱了大量寶貴經驗。我們自研了眾多基礎 JS 庫,落地了海量前端效果組件,也打磨出成熟的 OPOA 框架與 API 組件。這一系列文章,想與同行分享其中的一些思考,而今天,我們先從最基礎卻最容易被忽視的一環聊起——JavaScript 的編碼規範。
眾所周知,JavaScript 是一門語法極具彈性的語言。它誕生之初,僅是為了給 HTML 頁面添加一些動態效果。正因為動態、弱類型等特性,加上各家瀏覽器千差萬別的兼容表現,它的開發成本往往比 Java 這類語言高出不少。也恰恰是這份「過度靈活」,讓我們下定決心制定一套適用於網易郵箱的 JavaScript 編碼規範,盡可能把因語法隨意而埋下的隱患降到最低。下面就逐一展開說明。
這裡所說的變量,涵蓋了全局變量、局部變量、類變量以及函數參數等各種類型,它們都遵循同一套規則。
變量名由「類型前綴 + 有意義的單詞」組合而成,單詞首字母一律大寫。例如:sUserName、nCount。
每個局部變量都應帶有一個標明類型的字母前綴,具體對應如下:
sName、sHtmlnPage、nTotalbChecked、bHasLoginaList、aGrouprDomain、rEmailfGetHtml、fInitoButton、oDate當然也有兩種例外:其一,作用域很小、生命週期很短的臨時變量可以簡寫,比如 str、num、bol、obj、fun、arr;其二,循環計數變量可以簡寫,比如 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
}
而如果採用了全局變量前綴,語義瞬間就一目了然。
統一採用「動詞」或「動詞 + 名詞」的形式,例如 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()。
netease.events.mouse.Handler,而非冗長的 netease.events.mouse.MouseEventHandler。bIsNotError、bIsNotFound,都不值得提倡。for(var i=0,m=10;i<m;i++){ do something }。if((i=3)>2){},不可取。nTotal = 100。