我的代碼規範分享

前言

本文總結了下我在前端開發過程當中編寫JavaScript的一些習慣的代碼規範，之前端開發背景爲主，但有些規則也適用其餘語言。同時此規範並不絕對，僅供參考。

命名規範

變量長度：
變量名不要太長，儘可能不超過5個單詞，若太長可使用單詞縮寫

變量縮寫：
變量縮寫能夠採用兩種縮寫方案：

1.使用單詞前幾個字母，能表述含義便可，控制在3-5個字母（具體長度自定）。如：

醫院：hosp
醫生：doc
選項：opt

2.若頁面內同時出現「文檔」和「醫生」那麼doc會衝突，能夠適當增長長度或變換單詞來區分。如：

文檔：docs
醫生：doct

3.使用單詞的重音字母，令人能看到字母聯想到單詞。如：

產品：pdt
配置：cfg
檢查：chk

函數命名

操做類函數：
通常使用動詞，配合各種形容詞，大體以下：
1.純動詞。如：

save()
delete()
close()

2.動詞+名詞。如：

保存醫生：saveDoc()
刪除醫院：delHosp()
建立產品：createPdt()

3.動詞+形容詞+名詞。如

刪除選中的醫生：delSelectDoc()
追加一個臨時醫院：appendTempHosp()
保存全部產品：saveAllPdt()

獲取數據類函數：
統一使用get開頭。如：

getDocList()
getDisablePdt()
getElementById(id)

從網絡獲取數據類函數：
統一使用load開頭。如：

獲取省份數據：loadProvince()
根據省份ID獲取市區數據：loadCityByProvinceId(pid)
根據市區ID獲取縣數據：loadCountyByCityId(cid)

load與get的區別我的認爲在於，get更通用，能夠用於代碼內部的數據處理邏輯，load更傾向於從遠程加載。

事件響應函數：
on+(動詞/操做)+元素+事件名。如

點擊保存按鈕：onSaveBtnClick()
點擊添加按鈕：onAddBtnClick()
當是否可用複選框變動時：onIsEnableChkChange()
頭像圖片鼠標移入時：onHeaderImgMouseEnter()

也能夠是on+元素+(動詞/操做/用途)+事件名。如

onBtnSaveClick()
onChkIsEnableChange()

看我的習慣便可。

雖然看上去略繁瑣，但經過函數名自己，就能夠完整的定位到此函數的用途。例如onIsEnableChkChange函數名：

1. 看到on開頭，知道這是一個響應界面操做事件的函數
2. 看到isEnable，知道這是「是否可用」的功能的元素。
3. 看到chk，知道這是一個複選框checkbox元素的事件
4. 看到末尾的Change，知道這是一個change事件的響應函數
5. 綜上，看到命名，就能夠聯想到網頁上有一個 名叫xxx是否可用的複選框，這是點擊了這個複選框後的事件

變量命名

變量單詞鏈接符：
不使用單詞鏈接符，使用小駝峯式命名。如

btnSaveClick

布爾值類型變量：
統一使用is開頭。如

是否可用：isEnable
是否選中：isCheck
是否刪除：isDelete

集合類型變量：
統一使用List結尾。如

食品列表：foodList
醫生列表：docList
已選產品列表：selectPdtList

數組循環體內臨時變量：
若循環體代碼量少，或僅一行lambda表達式，則可簡寫 doc或d, pdt或p
循環體代碼量大時，或嵌套循環時，儘可能使用Item結尾。如docItem, pdtItem
不強制要求，僅爲區分層級關係

字典變量：
統一使用Dic（Dictionary）結尾，如

openWithDic
exeDumpDic

枚舉集合：
統一使用Enum（Enumeration）結尾。如

醫生類型枚舉：docTypeEnum
產品狀態枚舉：pdtStatusEnum
服務器狀態碼枚舉：serverCodeEnum

枚舉項：
建議使用全大寫，使用下劃線鏈接單詞，與常量規則一致。如

服務器返回值失敗：serverCodeEnum.ERROR
服務器返回值成功：serverCodeEnum.SUCCESS

jQuery變量：
建議使用$開頭，或J_開頭，風格統一便可。

$saveBtn
J_saveBtn

函數變量：
建議使用Fn或Cb結尾，標明此變量爲函數指針。如

鉤子函數：hookFn
響應回調函數：responseCb
回調函數：callback

常量：
統一使用全大寫字母，單詞用下劃線鏈接。如

MAX_SIZE
TIME_OUT

類（Class）構造函數：
統一使用大駝峯式命名。如

ListView
DataTable
TableView

類私有屬性：
若是未使用TypeScript或其餘強類型語言，即若沒有使用帶有訪問修飾符（public，private等）的語言開發，應該經過變量名自己便可區分是私有屬性仍是公開屬性。
私有屬性以及私有函數，應統一如下劃線開頭。如

_data
_pdtList
_getData()
_setData()

目的在於給與類的使用者能夠經過變量區分，哪些是可使用的公開屬性和方法，哪些不該該使用的私有屬性以及不該該調用的私有方法。

組件事件命名：
1.統一使用on開頭。如

onClick(e)
onSubmit(e)

2.關鍵流程類事件，應提供after事件和before事件，以onBefore和onAfter開頭。如

準備提交前事件：onBeforeSubmit
提交後事件：onAfterSubmit
準備展開前事件：onBeforeExpand
刪除後事件：onAfterDel

3.屬性/狀態變動類事件，應以on開頭，changed結尾。如

check屬性變動時事件：onCheckedChange
select屬性變動時事件：onSelectedChange
產品狀態變動時事件：onPdtStatusChange

代碼建議

1. 善用變量緩存
2. 重複使用屢次的字符串必須緩存
3. 善用枚舉變量，減小後期維護成本
4. 類方法應所有掛載到原型對象
5. 不該該使用類私有全局變量，應使用類靜態變量
6. 儘可能減小閉包代碼，以減小可能會出現的問題的機率
7. 應堅持「先定義，後使用」的規範。以減小js默認的定義提高的坑
8. 整個代碼應該應只有一個入口函數，即建立一個init函數，來執行全部初始代碼，而不是整篇代碼隨定義，隨執行
9. 事件綁定類函數應放在同一處執行，減小維護成本
10. 善用#region 建立代碼塊，不一樣功能的代碼歸類，初始化類，事件綁定類，界面交互類，純數據處理工具類等。
11. 模塊類文件，全部導出變量應所有定義在尾部。方便查閱
12. 儘量不建立全局變量，不註冊全局事件，爲後期方便轉型爲單頁應用
13. 儘可能將代碼純數據邏輯與界面交互邏輯分開，方便後期寫測試用例
14. 儘可能將全部變動定義放置在 文件/函數 內頂部
15. 善用try catch和throw Error
16. 不要在數組內存放不一樣類型的數據，一個數組應只存放一種數據類型變量，方便強類型識別與糾錯
17. 儘量不要建立類數組變量
18. 儘量不使用eval、with
19. 多寫註釋！推薦jsdoc風格註釋，方便一鍵抽取註釋生成代碼文檔
20. 推薦使用flowjs或ts等類型描述語言來約束、規範、糾錯和智能感知。

附：關於js中的對象、字典與枚舉的關係

以上我的經驗在組內分享時，有同窗提出疑問：

爲何會有字典變量，以及枚舉變量，這從本質上不都是Object對象麼？

關於這個問題我是這麼理解的，在js中確實對象是最強大的，任何在其餘語言當中的相似對象的數據結構，在js裏均可以是對象。但也正由於如此寬泛，讓咱們的使用過程當中會產生一些疑惑或誤解，才須要對各類的對象作分類。
因此回過頭來再說對象，字典與枚舉的關係。

他們的相同點：
他們都是鍵值對集合（KeyValuePair）
他們的Key都不能重複

他們的不一樣點：
對象：
對象的的Key能夠是字符串類型或數值類型。若是同時包含這兩種就類數組對象，好比document.getElementBy...系列函數的返回值：HTMLCollection，再好比HTML元素的子元素集合：NodeList，以及HTML元素的屬性值：NamedNodeMap，等都是類數組對象。
對象的Value的類型，能夠是任意類型。並且是在一個對象變量中的Value均可以是任意類型，如JSON對象。

字典：
而字典的Key必定是字符串類型的（其餘語言中不是，受限於js語言），字典的Value也能夠任意類型，但在一個字典對象變量中的全部Value必定是相同類型，也就是說字典實際上是個Object<string, TValue>。
例：好比前面剛剛提到的HTML元素的attributes屬性值：NamedNodeMap，就是應該一個典型的字典對象：它屬於Dictionary<string, Attr>。
可是奇葩的是NamedNodeMap也支持數組下標式訪問，因此它同時也是一個List<Attr>，在js裏只能歸結於他是類數組對象的範疇內了。


枚舉：
而最後的枚舉對象的範圍會更小，枚舉的值通常爲基本數據類型，在其餘語言中甚至只能是數值類型。
例如，定義一個枚舉對象用於一組常量：

// 服務器接口返回值狀態碼枚舉
var serverCodeEnum = {
    SUCCESS : 0,
    ERROR : 1,
    XXXXX : 2,
    XXXXX : 3,
}

TypeScript中的枚舉變量

在TypeScript爲了照顧js語言的平常使用，把enum關鍵字的編譯後代碼作成了雙向訪問的類數組對象。
也就是既能夠用過名稱得到數值，也能夠經過數值得到名稱。使用很是方便：

【TypeScript代碼中的枚舉】
enum ownerTypeEnum {
    public = 0,
    private
}

【編譯爲JS後的代碼】
var ownerTypeEnum;
(function (ownerTypeEnum) {
    ownerTypeEnum[ownerTypeEnum["public"] = 0] = "public";
    ownerTypeEnum[ownerTypeEnum["private"] = 1] = "private";
})(ownerTypeEnum || (ownerTypeEnum = {}));

// 效果：
// ownerTypeEnum.private -> 1
// ownerTypeEnum[1] -> "private"

最後

此類文章很是容易引戰，因此再次聲明以上僅我的習慣以及經驗的分享，每一個人都有本身的習慣，無論採用哪一種習慣其實均可以。 至少應該在組內，或是某項目內的全部成員都採用相同的一套規範，作到見名知意。