前端開發變量命名系列 - 開篇

時間 2019-11-08

原文原文鏈接

程序開發過程當中變量命名不只是一個頭疼問題，也是一個對開發者綜合素質的檢驗，它會直接影響到代碼的最終交付質量、代碼Review人員心智承受力。如何寫出具備創造性、優雅性、易讀性的高質量代碼，須要開發者在實際工做中不斷總結、提煉，在閱讀他人代碼時不斷地吸取，並在必定的編碼規範上造成本身的編碼風格。在代碼一道除了天資和經驗更須要一份詳實的參考來輔助，這正是本系列文章的出發點所在。javascript

變量的命名不侷限於JavaScript代碼中的屬性、方法和對象，也包含了路由的命名，工程結構的命名，數據庫表和字段的命名，樣式中Class和ID選擇器的命名，HTML元素的選擇等。html

本系列將分紅多篇來分析前端開發過程當中變量命名所涉及到的知識點，規劃以下：前端

前端開發變量命名系列 - 開篇
前端開發變量命名系列 - JavaScript篇
前端開發變量命名系列 - HTML及UI組件篇
前端開發變量命名系列 - CSS篇
前端開發變量命名系列 - NodeJs篇
前端開發變量命名系列 - 工程目錄結構篇
前端開發變量命名系列 - 經常使用英文詞彙篇

因爲我的寫做水平和技術實力及經驗有限，一家之言，不免服衆，更況且我的在圈子中沒有任何名氣和背景。因此在Github上爲此專門開了一個組織Code Naming Guide，其內容不限於前端開發領域，前端部分地址爲code-naming-guide/frontend。但願更多的同行一塊兒參與進來共同完善和維護。vue

注意：目前只暫時佔了個github的名，等到全部（部分）系列文章完結後，再從總體的角度去思考如何組織github中的內容及分類。在閱讀文章的過程當中有疑問和更好的建議歡迎留言或者微信: jenemy_xl

背景

在編碼的過程當中變量命名是一個容易忽略，又容易犯頭疼的問題。例如在複雜的頁面佈局中Class的命名，一樣一個結構在不一樣的上下文要表達的意思不同，是採用通用命名呢？仍是採用更具備描述性的業務相關詞彙？可是呢還須要考慮到樣式的複用、是否會衝突、被覆蓋、組合命名的長度是否太長等問題。java

在實際工做中，每一個人都有本身命名風格和慣用詞彙，有的喜歡使用英文簡寫、有的喜歡使用中英文結合、有的喜歡給變量加數據類型前綴、有的喜歡亂造詞彙、有的甚至單詞都拼寫不正確。在看別人代碼的過程當中你是否像我同樣無語，但也只能截圖指出並吐槽二下，有些時候對方並不買單，改正。git

每次到換工做的時候就更新博客，7月下旬的高溫天氣就適合在家裏碼字，此次選擇這個話題的緣由是目前在網上尚未相關的文章來系統全面的論述有前端關代碼變量命名的資料。Java有《碼出高效 - 阿里巴巴Java開發手冊終級版》，而前端這方面目前仍是一個空白，雖然有不少代碼規範，可是不多有人願意在這方面去花心思，更多的是研究框架的源碼、數據結構與算法和嘗試新的技術，本人因爲大腦開發有限、沒有能力去啃這些骨頭，只好撿一些不多有人去碰觸的簡單不費腦的知識點來考究一二，但願也能爲前端的生態作出一點小貢獻。github

命名規則

目前流行的經典命名規則有：駝峯命名法、匈牙利命名法、下劃線命名法、帕斯卡命名法算法

相關命名的具體規則請另行查閱。前端主要涉及到駝峯命名法，React組件會用到帕斯卡命名法。typescript

而後是變量命名規則：數據庫

變量名首字母必須爲字母(a-z A-Z)，下劃線(_)，或者美圓符號($)開始
變量名只能是字母(a-z A-Z)，數字(0-9)，下劃線(_)的組合，而且之間不能包含空格，數字不能放在變量名首位。
變量名不能使用編程語言的保留字。好比在javascript中不能使用true, false, while, case, break保留字等等。

命名風格

這裏給出一些在開發過程當中約定成俗的通用規則，涉及JavaScript, Typescript, 框架組件, 樣式及目錄。在文章中將使用【強制】來表示必須嚴格遵照，【推薦】來表示建議，【參考】來給出多種命名方式的一種。

1. 【強制】在JavaScript中使用駝峯命名法來表示變量，不能如下劃線或美圓符號做爲開始和結束。

// 反例
_name
__name
name_
$name
name$

補充：因爲受框架和第三方庫及語言限制，不可能徹底避免。例如：在RxJs中一般命名流的時候是以 變量名 + $ 的形式，在Class中定義私有變量時一般以 _ + 變量名 的方式來表示，在Vue中內部實例方法所有以 $ 開始，在AngularJs中內部方法以 $$ 開始，而lodash直接使用 _ 做爲其別名。

2. 【強制】在代碼中嚴禁使用拼音與中英文混合的方式，更不容許直接使用中文的方式。除了一些國際通用的中文名稱，要視爲英文外，其它禁止使用。

// 正例
taobao
tmall
shanghai
coupons

// 反例
yhq [優惠券]

3. 【強制】類名使用大寫駝峯命名法來表示，Typescript中枚舉值使用大寫駝峯命名法表示。

// 正例
class User {}
enum Color {Red = 1, Green, Blue}

// 反例
class user {}

4. 【強制】常量名所有大寫，單詞間使用下劃線隔開，力求表達完整清楚，不要嫌名字長。

// 正例
GOOGLE_MAP_TOKEN

// 反例
TOKEN

5. 【建議】Typescript中抽象類使用 Abstract 或 Base 開頭；異常類使用 Exception 結尾。

abstract class BaseDepartment {}

6. 【建議】在TypeScript中，類型使用 Type 做後綴，接口使用 I 做爲前綴。

type PropsType = {}
interface ILoginProps {}

7. 【建議】採用有意義的命名，在項目中堅持使用一種變量命名方式。不要 usr 與 user 混用

// 正例
users
getUserByUid()

// 反例
registerUsr()
copyUserInfo()

8. 【建議】方法名必須準確表達該方法的行爲，在多數狀況下以動詞開頭。

// 正例
fetchCoupons()
updateToken()
createAccount()
generateUniqueId()

// 反例
getData()

9. 【建議】可使用單詞簡寫，可是隻侷限於經常使用詞彙，注意不一樣詞彙的簡寫有可能衝突。

// 正例
setProps() [props -> property]
selectCouponsDlg() [dlg -> dialog]
readPkg() [pkg -> package]
previewTpl [tpl -> template]

// 反例
vehicleDesc [desc -> description]
vehicleDesc [desc -> descending]
vehicleAesc [aesc -> aescending]
fetchUsr() [usr -> user]

10. 【建議】在Vue和Angular中，模板語法中全部組件名使用中線命名法，在React中使用大寫駝峯命名法來表示。

// Vue
<el-button type="text" @click="toDetail">詳情</el-button>
<custom-component a-prop="prop" />

// Angular
<nz-sider [nzWidth]="200" style="background:#fff"></nz-sider>

// React
<SelectPicture data={this.images} />

11. 【推薦】統一使用中線命名法來命名目錄。

|-- page-header
|   |-- PageHeader.vue

12. 【參考】在Vue模板語法中組件屬性使用連字符命名法，在Vue中使用JSX則屬性使用駝峯命名法，而且文件文以」.jsx」爲文件類型。

<Thumbnail
  withHeadPicture={true}
  data={this.selectedImages[0]}
  withDetail={this.enabledDetail}
/>

13. 【強制】在服務名上使用 Service 後綴

class UserService {}

14. 【建議】在Vue中組件文件名採用大寫駝峯命名方式，React一樣如此，在Angular中以使用點和橫槓來分隔文件名，而且符號名後面追加約定的類型後綴。

// Vue
User.vue

// Angular
app.component.ts
hero-list.component.ts
validation.directive.ts
app.module.ts
user-profile.service.ts

// React
User.jsx

15. 【參考】在React中使用目錄名稱做爲組件名，在目錄內容直接使用index做爲入口，在Vue中不能夠，在Angular中能夠將index做爲模塊的入口，固然也能夠直接做爲組件的入口，但這樣和其整個命名風格有所背離。

// Vue
|-- user-info
|  |-- UserInfo.vue

// Angular
|-- user-info
|  |-- user-info.component.ts
|  |-- index.ts

// React
|-- user-info
|   |-- index.jsx

16. 【建議】在工程中文檔使用全大寫命名

README.md
CONTRIBUTORS.md
CHANGELOG.md

17. 【建議】在Vue中指令命名使用 filter 做爲結束。全部引用命名使用 ref 做爲後綴

formatCouponsFilter
inputRef
selectRef

18. 【強制】測試文件以 .spec 或者 .test 做爲命名的一部分。

selectPicture.spec.js
pageHeader.test.js

19. 【建議】複數化變量名稱，而不是命名中包含集合類型名稱。

// 正例
hosts
users
validUsers
hostText
hostJson
portNumber

// 反例
hostList
userList
hostStr
intPort

20. 【建議】在 for 循環中使用 i, j, k 來做爲索引，使用 n 表示數量/次數/限制，使用 e 表示異常, 使用 evt 表示事件對象, 使用 cb 表示回調函數。

for (let i = 0; i < 10; i++) {
  for (let j = 0; j < 10; j++) {
    for (let k = 0; k < 10; k++) {
      // do something
    }
  }
}

21. 【強制】在解構時使用 const 來聲明。

const [ foo, bar ] = { foo: 1, bar: 2 }

22. 【建議】在樣式中Class命名可使用一些經常使用簡寫來減小長度。

hd -> head
hdr -> header
ft -> foot
ftr -> footer
pg -> page
btn -> button
txt -> text
el -> element
opt -> option
bd -> border
cl -> clearfix
p -> padding
m -> margin
l -> left
r -> right
t -> top
b -> bottom
x -> horizontal
y -> vertical
px -> padding-left, padding-right
py -> padding-top, padding-bottom
pl -> padding-left
m -> margin
dlg -> dialog
sel -> select
img -> image
lbl -> label
chk -> checkbox
tpl -> template
tbl -> table
hoz -> horizontal
vert -> vertical
ref -> reference
wiz -> wizard
oh -> overflow: hidden

補充：有些簡寫不能單獨使用，終須組合才能使用，例如: p, m, x, y等單個詞彙。

23. 【建議】在命名時採用BEM的方式，並適當變化，具體參見後續文章。

.page-header__main
.dialog__content
.gallery-list--wrap
.thumbnail-image--info
.action__btn-group

24. 【建議】樣式Class命名使用中線鏈接，ID命名採用下劃線鏈接。Class能夠同時採用中線和下劃線，但要遵循必定的規則。

.thumbnail-item__image
#page_header

25. 【參考】樣式Class採用組合方式，經過外層Class名來限制做用範圍。

// 正例
<div class="page-header">
  <div class="page-header__wrap common"></div>
  <div class="page-header__wrap tab"></div>
</div>

// 反例
<div class="page-header">
  <div class="page-header__wrap page-header--common"></div>
  <div class="page-header__wrap page-header--tab"></div>
</div>