[[273665]]

JavaScript作為前端開(kāi)發(fā)從業(yè)人員必須掌握的3大基礎(chǔ)知識(shí)中最重要的一環(huán)，也是平是接觸時(shí)間最長(zhǎng)、寫(xiě)得最多的。在開(kāi)發(fā)過(guò)程中必然會(huì)遇到命名的問(wèn)題，你會(huì)詞窮、糾結(jié)、惆悵嗎？本文的出現(xiàn)相信能夠解決大部分煩惱，讓你輕松寫(xiě)出符合規(guī)范、易讀、簡(jiǎn)短的代碼。

本文將通過(guò)大量的實(shí)例來(lái)試圖自圓其說(shuō)，形成一套系統(tǒng)化、實(shí)用的變量命名理化體系。通過(guò)按JavaScript的數(shù)據(jù)類(lèi)型分類(lèi)著手、細(xì)到一個(gè)函數(shù)的參數(shù)命名，并提供眾多可選方案，并盡量給出其適用范圍和利弊。

需要注意的是由于個(gè)人寫(xiě)作水平、和知識(shí)有限，很多方面敘述上有些生硬，在分類(lèi)上也沒(méi)有什么特別的依據(jù)，文章也沒(méi)有人審稿，所以有什么紕漏還請(qǐng)留言告知。由于寫(xiě)作倉(cāng)促，內(nèi)容可能不全，后續(xù)會(huì)隨著工作和學(xué)習(xí)的深入而不斷地調(diào)整和更新。

布爾值(Boolean)命名

Boolean值是兩種邏輯狀態(tài)的變量，它包含兩個(gè)值：真和假。在JavaScript中對(duì)應(yīng) true 和 false，在實(shí)踐中通常使用數(shù)字1表示真值，0來(lái)表示假值。

雖然Boolean的狀態(tài)只有兩種但是在命名時(shí)可以進(jìn)一步分類(lèi)，這里給出幾種場(chǎng)景：

•  場(chǎng)景一：表示可見(jiàn)性、進(jìn)行中的狀態(tài)

解釋?zhuān)嚎梢?jiàn)性在通常指頁(yè)面中的元素、組件是否顯示（或者組件掛載到DOM上，但并不可見(jiàn)）。進(jìn)行中主要是說(shuō)明某種狀態(tài)是處于持續(xù)進(jìn)行中。

推薦命名方式為 is + 動(dòng)詞（現(xiàn)在進(jìn)行時(shí)）/形容詞，同時(shí)這種方式也可以直接不寫(xiě) is，但是為了更好的作區(qū)分，建議還是加上。 

{  
  isShow: '是否顯示',  
  isVisible: '是否可見(jiàn)',  
  isLoading: '是否處于加載中',  
  isConnecting: '是否處于連接中',  
  isValidating: '正在驗(yàn)證中',  
  isRunning: '正在運(yùn)行中',  
  isListening: '正在監(jiān)聽(tīng)中'  
} 

注意： 在Java中使用這種方式是有一定副作用的，為什么請(qǐng)移步：為什么阿里巴巴禁止開(kāi)發(fā)人員使用 “isSuccess” 作為變量名？ 

•  場(chǎng)景二：屬性狀態(tài)類(lèi)

解釋?zhuān)和ǔＳ脕?lái)描述實(shí)體（例如：HTML標(biāo)簽、組件、對(duì)象）的功能屬性，而且定法比較固定。 

{  
  disabled: '是否禁用',  
  editable: '是否可編輯',  
  clearable: '是否可清除',  
  readonly: '只讀',  
  expandable: '是否可展開(kāi)',  
  checked: '是否選中',  
  enumberable: '是否可枚舉',  
  iterable: '是否可迭代',  
  clickable: '是否可點(diǎn)擊',  
  draggable: '是否可拖拽'  
} 

•  場(chǎng)景三：配置類(lèi)、選項(xiàng)類(lèi)

解釋：主要是指組件功能的開(kāi)啟與關(guān)閉，功能屬性的配置。

這是一種比較常見(jiàn)的情景，目前命名方式也有很多種，但是歸納起來(lái)也不多。推薦使用 withXx 來(lái)表示組件在基本功能形態(tài)外的其它功能，比如組件的基礎(chǔ)功能到高級(jí)功能的開(kāi)啟；使用 enableXx 來(lái)表示組件某些功能的開(kāi)啟；使用 allowXx 來(lái)表示功能屬性的配置；使用 noXx 用于建議功能使用者這個(gè)不建議開(kāi)啟。 

{  
  withTab: '是否帶選項(xiàng)卡',  
  withoutTab: '不帶選項(xiàng)卡',  
  enableFilter: '開(kāi)啟過(guò)濾',  
  allownCustomScale: '允許自定義縮放',  
  shouldClear: '是否清除',  
  canSelectItem: '是否能選中元素',  
  noColon: '不顯示label后面的冒號(hào)',  
  checkJs: '檢查Js',  
  emitBOM: 'Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.'  
} 

注意：如果嫌分類(lèi)太多，可以只使用其中一種方式，比如在Typescript中使用了 allownXx 和 noXx。

除了上面這些帶有特定的前置介詞、動(dòng)詞方式外還有一些在語(yǔ)義上帶有疑問(wèn)性質(zhì)的組合通常也是作為Boolean命名的一種參考。 

{  
  virtualScroll: '是否啟用虛擬滾動(dòng)模式',  
  unlinkPanels: '在范圍選擇器里取消兩個(gè)日期面板之間的聯(lián)動(dòng)',  
  validateEvent: '輸入時(shí)是否觸發(fā)表單的校驗(yàn)'  
} 

函數(shù)命名

函數(shù)在不同的上下文中的叫法也不一樣，在對(duì)象中稱(chēng)為方法，在類(lèi)中有構(gòu)造函數(shù)、在異步處理時(shí)有回調(diào)函數(shù)，還有立即執(zhí)行函數(shù)、箭頭函數(shù)、柯里函數(shù)等。

函數(shù)命名的方式常常是和業(yè)務(wù)邏輯耦合在一起的，但是在命名規(guī)則上也有一些常見(jiàn)的模式可以遵循。

•  場(chǎng)景一：事件處理

事件處理函數(shù)是前端平時(shí)用到最多的，包括瀏覽器原生事件、異步事件和組件自定義事件。在寫(xiě)法上最常見(jiàn)的兩種命名分別為 onXx、onXxClick和handleXx、handleXxChange。

這里如何在二者之間選擇，可以從二方面來(lái)歸類(lèi)。一是，原生事件采用 onXx，而自定義事件使用 handleXx。二是，事件主動(dòng)監(jiān)聽(tīng)采用 onXx，被動(dòng)處理使用 handleXx。

從實(shí)踐及三大主流框架的文檔關(guān)于事件部分的內(nèi)容來(lái)看，推薦使用 handleXx 這種方式，而在表單提交的時(shí)候通常采用 onSubmit 函數(shù)。

其實(shí)，在實(shí)際項(xiàng)目中很少?lài)?yán)格這樣來(lái)命名事件處理函數(shù)，因?yàn)檫@種方式有一定的局限性，比如點(diǎn)擊按鈕打開(kāi)一個(gè)對(duì)話(huà)框，使用 handleOpenDlg 和 onOpenDlg 都沒(méi)有直接寫(xiě) openDlg 方便，如果頁(yè)面有多個(gè)不同功能的對(duì)話(huà)框采用這種方式會(huì)顯得變量名過(guò)長(zhǎng)，而handle和on就顯得沒(méi)有必要了，比如 hanldeOpenCommentDlg 就沒(méi)有 openCommentDlg 直白。

下面列出了一些約定成俗的適用例子： 

{  
  onSubmit: '提交表單',  
  handleSizeChange: '處理分頁(yè)頁(yè)數(shù)改變',  
  handlePageChange: '處理分頁(yè)每頁(yè)大小改變',  
  onKeydown: '按下鍵'  
} 

•  場(chǎng)景二：異步處理

這里主要是指在寫(xiě)數(shù)據(jù)層服務(wù)、狀態(tài)管理中的Action命名，以及Ajax回調(diào)的命名規(guī)則。 

{  
  getUsers: '獲取用戶(hù)列表',  
  fetchToken: '取得Token',  
  deleteUser: '刪除用戶(hù)',  
  removeTag: '移除標(biāo)簽',  
  updateUsrInfo: '更新用戶(hù)信息',  
  addUsr: '添加用戶(hù)',  
  createAccount: '創(chuàng)建賬戶(hù)'  
} 

命名主要圍繞數(shù)據(jù)的增刪查找來(lái)劃分，獲取數(shù)據(jù)通常是 getXx 和 fetchXx，在作者看來(lái)兩者在使用上的區(qū)分在于 getXx 的數(shù)據(jù)來(lái)源不一定直接取自異步的原始數(shù)據(jù)，可能是加工處理后的，而 fetchXx 是直接拿的原始數(shù)據(jù)。當(dāng)然在實(shí)際項(xiàng)目中并沒(méi)有區(qū)分，看個(gè)人喜好。

deleteXx 主要用于數(shù)據(jù)刪除，而 removeXx 在語(yǔ)義上是移除數(shù)據(jù)，通常情況數(shù)據(jù)是還存在的，只是沒(méi)有顯示或數(shù)據(jù)假刪除。updateXx 是指數(shù)據(jù)更新操作，addXx 是在已有列表數(shù)據(jù)中添加新的子項(xiàng)、而createXx 主要是創(chuàng)建新的實(shí)例，比如新建一個(gè)賬戶(hù)。

•  場(chǎng)景三： 跳轉(zhuǎn)路由

在實(shí)際開(kāi)發(fā)過(guò)種中，比如在使用react-router/vue-router時(shí)，在模板或者JSX中可以直接在標(biāo)簽中寫(xiě)上目標(biāo)地址，但有些時(shí)候跳轉(zhuǎn)的目標(biāo)地址是經(jīng)過(guò)判斷或者組合后的，并且通過(guò)事件觸發(fā)跳轉(zhuǎn)的，這個(gè)時(shí)候就需要一個(gè)函數(shù)來(lái)處理，那么在函數(shù)命名的時(shí)候可以考慮使用 

{  
  toTplDetail: '跳轉(zhuǎn)到模板詳情頁(yè)面',  
  navigateToHome: '導(dǎo)航到首頁(yè)',  
  jumpHome: '跳轉(zhuǎn)首頁(yè)',  
  goHome: '跳轉(zhuǎn)首頁(yè)'  
} 

推薦使用 toXx 和 goXx 這兩種方式，如果不是在當(dāng)前頁(yè)面打開(kāi)/跳轉(zhuǎn)頁(yè)面，可以使用 toBlankTplDetail 或者 goBlankHome 這種方式來(lái)進(jìn)一步語(yǔ)義化。如果前端頁(yè)面是位于Webview中，也可以考慮采用 toNativeShare 這種方式來(lái)命名。

•  場(chǎng)景四：框架相關(guān)特定方法

這里主要是針對(duì)前端3大主流流行框架，有一些命名是帶有特定標(biāo)識(shí)符的，還有就是一些生命周期的命名方式。 

{  
  formatTimeFilter: '在AngularJs和Vue中，通常用于過(guò)濾器命名',  
  storeCtrl: '用于AngularJs定義控制器方法',  
  formatPipe: '用于Angular中，標(biāo)識(shí)管道方法',  
  $emit: 'Vue中的實(shí)例方法',  
  $$formatters: 'AngularJs中的內(nèi)置方法',  
  beforeCreate: 'Vue的生命周期命名',  
  componentWillMount: 'React生命周期命名',  
  componentDidMount: 'React生命周期命名',  
  afterContentInit: 'Anuglar生命周期命名',  
  afterViewChecked: 'Angula生命周期命名',  
  httpProvider: 'AngularJs服務(wù)',  
  userFactory: '工廠(chǎng)函數(shù)',  
  useCallback: 'React鉤子函數(shù)'  
} 

•  場(chǎng)景五：數(shù)據(jù)的加工

這類(lèi)場(chǎng)景在處理列表的時(shí)候經(jīng)常會(huì)碰到，比如排序、過(guò)濾、添加額外的字段、根據(jù)ID和索引獲取特定數(shù)據(jù)等。

情形一：根據(jù)特定屬性獲取屬性

這里可以參考DOM方法的命名，比如：getElememtById()、getElementsByTagName()、getElementsByClassName() 和 getElementsByName()，然后提煉出一個(gè)比較實(shí)用的模板：getXxByYy()。其中 Xx 可以是：element, item, option, data, selection, list, options 以及一些特定上下文的名字，比如：user(s), menu(s) 等。Yy 相對(duì)來(lái)說(shuō)比較固定，經(jīng)常用到的就是 id, index, key, value, selected, actived 等。

除了使用 get，還可以使用 query 和 fetch，但是需要注意和上面提到的異步數(shù)據(jù)處理作一個(gè)區(qū)分。 

{  
  getItemById: '根據(jù)ID獲取數(shù)據(jù)元素',  
  getItemsBySelected: '根據(jù)傳入的已選列表ID來(lái)獲取列表全部數(shù)據(jù)',  
  queryUserByUid: '根據(jù)UID查詢(xún)用戶(hù)'  
} 

注意：在 getItemsBySelected 這種情形下直接寫(xiě)成 getItemsSelected 更好，但只適用于 Yy 為形容詞的場(chǎng)景

情形二：格式化數(shù)據(jù)

這里的格式化操作包括排序、調(diào)整數(shù)據(jù)結(jié)構(gòu)、過(guò)濾數(shù)據(jù)、添加屬性。命名通常使用 formatXx, convertXx, inverseXx, toggleXx, parseXx, flatXx, 也可以結(jié)合數(shù)組的一些操作方法來(lái)命名，比如 sliceXx, substrXx, spliceXx, sortXx, joinXx 等來(lái)命名。 

{  
  formatDate: '格式化日期',  
  convertCurrency: '轉(zhuǎn)換貨幣單位',  
  inverseList: '反轉(zhuǎn)數(shù)據(jù)列表',  
  toggleAllSelected: '切換所有已選擇數(shù)據(jù)狀態(tài)',  
  parseXml: '解析XML數(shù)據(jù)',  
  flatSelect: '展開(kāi)選擇數(shù)據(jù)',  
  sortByDesc: '按降序排序'  
} 

數(shù)組命名

數(shù)組的命名推薦使用復(fù)數(shù)形式來(lái)命名，還有就是名詞和具有列表意思的單詞組合。常見(jiàn)的詞匯有 options, list, maps, nodes, entities, collection 等。 

{  
  users: '用戶(hù)列表',  
  userList: '用戶(hù)列表',  
  tabOptions: '選項(xiàng)卡選項(xiàng)',  
  stateMaps: '狀態(tài)映射表',  
  selectedNodes: '選中的節(jié)點(diǎn)',  
  btnGroup: '按鈕組',  
  userEntities: '用戶(hù)實(shí)體'  
} 

選項(xiàng)元素、下拉元素命名

主要針對(duì)的是在下拉選擇框、選項(xiàng)卡元素、Radio、Checkbox等數(shù)據(jù)源每個(gè)選項(xiàng)數(shù)據(jù)的命名。常見(jiàn)的詞匯有：title, name, key, label, field, value, id, children, index, nodes 等。

基中 title/name/key/label/field 作為選項(xiàng)顯示名, value/id 用于唯一標(biāo)識(shí)選項(xiàng)，children/nodes 用于包含子節(jié)點(diǎn)內(nèi)容。如果選項(xiàng)元素的語(yǔ)義很明確的情況下也可以直接使用特定單詞來(lái)代替提到的這些泛指的詞匯，例如菜單列表就可以使用 menu 來(lái)作為顯示名。 

// 最常見(jiàn)組合  
{  
  title: '標(biāo)題',  
  value: 'ID值'  
}  
// 組合二  
{  
  label: '標(biāo)簽名',  
  value: 'ID值'  
}  
// 組合三  
{  
  name: '元素名',  
  id: 'ID值'  
}  
// 組合四  
{  
  field: '字段',  
  value: '標(biāo)識(shí)',  
  index: '索引'  
} 

當(dāng)前選項(xiàng)、激活項(xiàng)命名

適用列表的選中項(xiàng)、菜單選中項(xiàng)、步驟操作的當(dāng)前進(jìn)行步驟、頁(yè)面路由當(dāng)前路由等的命名。 

{  
  activeTab: '當(dāng)前選中選項(xiàng)卡',  
  currentPage: '當(dāng)前頁(yè)',  
  selectedData: '當(dāng)前選項(xiàng)中數(shù)據(jù)',  
} 

臨時(shí)數(shù)據(jù)、比對(duì)數(shù)據(jù)命名

針對(duì)在代碼中有時(shí)會(huì)使用一些臨時(shí)的變量來(lái)存儲(chǔ)數(shù)據(jù)、保存數(shù)據(jù)快照的場(chǎng)景下的命名。 

{  
  swapData: '臨時(shí)交換數(shù)據(jù)',  
  tempData: '臨時(shí)數(shù)據(jù)',  
  dataSnapshot: '數(shù)據(jù)快照'  
} 

數(shù)據(jù)循環(huán)語(yǔ)句中變量命名

在使用 for 循環(huán)時(shí)，多層嵌套請(qǐng)依次使用 i/j/k，超過(guò)3層可以使用 x/y/z，m/n 來(lái)命名。使用 forEach, map, filter 等方法時(shí)，每一個(gè)元素命名可以根據(jù)不同語(yǔ)境下的特殊名字來(lái)命名，比如遍歷 menus，那么每個(gè)元素可以命名為 menu，不然則使用上下文無(wú)關(guān)的詞匯，比如：item, option, data, key, object 等。至于索引通常使用 index，如果多層可以使用 index + 數(shù)字 的形式，也可以直接使用 i/j/k 來(lái)作為索引，甚至還可以使用 subIndex/grandIndex 這種方式來(lái)命名。

對(duì)于在使用 for 循環(huán)時(shí)數(shù)組長(zhǎng)度如果需要單獨(dú)命名的話(huà)，可以使用 xxlength/xxLens，或者 xxCount。

在循環(huán)的過(guò)程中通常還會(huì)統(tǒng)計(jì)某個(gè)條件下數(shù)據(jù)匹配的次數(shù)、重復(fù)元素?cái)?shù)量、記錄中間結(jié)果等情況。這里推薦使用 count 表示次數(shù)，skipped 表示跳過(guò)的數(shù)量，result 表示結(jié)果。 

// for 循環(huán)  
for (let i = 0; i < 10; i++) {  
  for (let j = 0; j < 10; j++) {  
    for (let k = 0; k < 10; k++) {  
      // do something  
    }  
  }  
}  
for (let i = 0, lens = this.options.length; i < lens; i++) {  
  // do something  
}  
// forEach  
users.forEach((item, index) => {  
  // do something  
})  
menus.forEach((menu, index) => {  
  if (menu.children) {  
    menu.children.forEach((subMenu, subIndex) => {  
      if (subMenu.children) {  
        subMenu.children.forEach((grandMenu, grandIndex) => {  
          // 一個(gè)不常用的示例  
        })  
      }  
    })  
  }  
}) 

方法參數(shù)命名

方法的參數(shù)名稱(chēng)和數(shù)量在不同的方法中各不相同，但是還是有一些固定的模式可以參考，比如在Vue中監(jiān)聽(tīng)屬性變化的新值和舊值；reduce 方法的上一個(gè)值，當(dāng)前值；回調(diào)函數(shù)的命名、剩余參數(shù)的命名等。

情形一：新值、舊值

常見(jiàn)于Vue中watch 對(duì)像中的屬性監(jiān)聽(tīng)回調(diào)函數(shù)，推薦使用 

{  
  oldVal: '舊值',  
  newVal: '新值'  
} 

情形二：上一個(gè)值、下一個(gè)值和當(dāng)前值

這種情形見(jiàn)于路由的鉤子方法，Object.assign 數(shù)據(jù)拷貝的參數(shù)。 

// 組合一  
{  
  from: '從...',  
  to: '到...'  
}  
// 組合二  
{  
  prev: '上一個(gè)...',  
  next: '下一個(gè)...',  
  cur: '當(dāng)前'  
}  
// 組合三  
{  
  source: '源',  
  target: '目標(biāo)'  
}  
// 組合四  
{  
  start: '開(kāi)始',  
  end: '結(jié)束'  
} 

情形三：異步數(shù)據(jù)返回

用于Promise的then方法參數(shù)，await 的返回的Promise等?？蛇x擇的詞匯有：res, data, json, entity，推薦使用 res。 

demoPromise.then(res => {  
  // do something  
}) 

情形四：其它情況

一些使用不多，但是在編程時(shí)約定成俗的命名方式。例如 ch 表示單個(gè)字符，str 表示字符串, n 代表次數(shù), reg 表示正則, expr 表示表達(dá)式, lens 表示數(shù)組長(zhǎng)度, count 表示數(shù)量, p 表示數(shù)據(jù)的精度, q 表示查詢(xún)(query), src 表示數(shù)據(jù)源(source), no 表示數(shù)字(number), rate 表示比率, status 表示狀態(tài), bool 表示布爾值, arr 表示數(shù)組值, obj 表示對(duì)象值, x 和 y 表示坐標(biāo)兩軸, func 表示函數(shù), ua表示User Agent, size 表示大小, unit 表示單位, hoz 表示水平方向, vert 表示垂直方向, radix 表示基數(shù)，根 

// 傳入單個(gè)字符  
function upper(ch) {}  
// 數(shù)量重復(fù)  
function repeat(str, n)  
// 正則  
'abab'.replace(reg, 'bb') 

事件命名

這里根據(jù)DOM、nodejs和一些框架和UI組件的事件進(jìn)行歸納

•  DOM事件

這里列舉DOM中常見(jiàn)的事件命名 

{  
  load: '已完成加載',  
  unload: '資源正在被卸載',  
  beforeunload: '資源即將被卸載',  
  error: '失敗時(shí)',  
  abort: '中止時(shí)',  
  focus: '元素獲得焦點(diǎn)',  
  blur: '元素失去焦點(diǎn)',  
  cut: '已經(jīng)剪貼選中的文本內(nèi)容并且復(fù)制到了剪貼板',  
  copy: '已經(jīng)把選中的文本內(nèi)容復(fù)制到了剪貼板',  
  paste: '從剪貼板復(fù)制的文本內(nèi)容被粘貼',  
  resize: '元素重置大小',  
  scroll: '滾動(dòng)事件',  
  reset: '重置',  
  submit: '表單提交',  
  online: '在線(xiàn)',  
  offline: '離線(xiàn)',  
  open: '打開(kāi)',  
  close: '關(guān)閉',  
  connect: '連接',  
  start: '開(kāi)始',  
  end: '結(jié)束',  
  print: '打印',  
  afterprint: '打印機(jī)關(guān)閉時(shí)觸發(fā)',  
  click: '點(diǎn)擊',  
  dblclick: '雙擊',  
  change: '變動(dòng)',  
  select: '文本被選中被選中',  
  keydown/keypress/keyup: '按鍵事件',  
  mousemove/mousedown/mouseup/mouseleave/mouseout: '鼠標(biāo)事件',  
  touch: '輕按',  
  contextmenu: '右鍵點(diǎn)擊 (右鍵菜單顯示前)',  
  wheel: '滾輪向任意方向滾動(dòng)',  
  pointer: '指針事件',  
  drag/dragstart/dragend/dragenter/dragover/dragleave: '拖放事件',  
  drop: '元素在有效釋放目標(biāo)區(qū)上釋放',  
  play: '播放',  
  pause: '暫停',  
  suspend: '掛起',  
  complete: '完成',  
  seek: '搜索',  
  install: '安裝',  
  progress: '進(jìn)行',  
  broadcast: '廣播',  
  input: '輸入',  
  message: '消息',  
  valid: '有效',  
  zoom: '放大',  
  rotate: '旋轉(zhuǎn)',  
  scale: '縮放',  
  upgrade: '更新',  
  ready: '準(zhǔn)備好',  
  active: '激活'  
} 

•  自定義事件

在封裝組件時(shí)提供的事件名除了參考DOM事件外，在命名上也可以參考Github Api 采用 動(dòng)詞過(guò)去時(shí) + Event 的方式 

{  
  assignedEvent: '分配事件',  
  closedEvent: '關(guān)閉事件',  
  labeledEvent: '標(biāo)簽事件',  
  lockedEvent: '鎖事件',  
  deployedEvent: '部署事件'  
} 

此外，很多命名方式可以根據(jù)場(chǎng)景使用 元素 + click 、元素 + change 、select + 范圍等方式靈活運(yùn)用 

{  
  selectAll: '選擇所有',  
  cellClick: '當(dāng)某個(gè)單元格被點(diǎn)擊時(shí)會(huì)觸發(fā)該事件',  
  sortChange: '當(dāng)表格的排序條件發(fā)生變化的時(shí)候會(huì)觸發(fā)該事件'  
}