前言

本文主要講前端開發(fā)時遇到的 編碼規(guī)范難以落地的問題 以及 解決方案 ，包括 編碼規(guī)范 和 git commit 規(guī)范。

重點在 落實前端團隊編碼規(guī)范 的操作上。跟著我一步一步去做，一定可以將規(guī)范落地。

問：要不要制定編碼規(guī)范？要不要使用 ESLint ？要不要規(guī)范化 git 的提交 ？

答：非個人項目 我都建議遵循團隊或主流的規(guī)范進行編碼。寫代碼和閱讀代碼是兩回事，團隊合作的話，代碼最好都能讓每個成員看著覺得舒服。git 的日志也同樣是這個道理，寫和讀是兩回事。

團隊開發(fā)的項目如果沒有開發(fā)規(guī)范：

• 日后維護成本大概率會變高。
• 可能看不懂同事的代碼（同事也不一定能看懂你的代碼）。
• 項目不容易擴展。
• 公司人員流動時，項目難以交接。
• 丑！

比如這樣的代碼就非常丑

const userInfo ={
  name: "張三",
  age:20,
  gender: '男'
}

function showUserInfo() {
  console.log('姓名：'+userInfo.name)
console.log("年齡：" + userInfo.age);
console.log("性別：" +userInfo.gender);
}

showUserInfo()

• 有些地方使用單引號，有些地方使用雙引號。
• userInfo ={...} 等號后面沒空格。
• age:20 冒號后面沒空格。
• showUserInfo 里的代碼有兩行沒用制表符排版。
• 有些代碼有加分號，有些代碼沒加分號。
• 字符串拼接時，部分加號兩邊沒空格。

雖然這段代碼是能運行的，但看上去就非常丑。甚至在很多公司中，這種代碼都是不合格的，大概率會公開處刑。

至于使用什么規(guī)范（比如要不要加分號），本文不做深入探討。
你可以按照團隊協(xié)商出來的規(guī)范去編碼，也可以使用大廠提供的規(guī)范。

???文末放了幾份大廠規(guī)范的鏈接~

規(guī)范化引發(fā)的問題

有規(guī)范是好事，但也因此引發(fā)一些問題：

• 團隊成員能力參差不齊，按照高標規(guī)范部分成員會被迫 降低開發(fā)效率。
• 新成員加入，難道要完整看一遍規(guī)范文檔？看完也不一定記得住。

解決方案

針對上述問題，現(xiàn)在比較流行的 解決方案是：自動化！

• 保存代碼時：自動格式化代碼，之后再檢測編碼是否符合團隊規(guī)范，不合規(guī)的提示錯誤。
• 提交代碼時：檢測編碼是否符合團隊規(guī)范，不合規(guī)不允許提交。
• 編寫commit message時：提供日志模板。

也就是說

• 用 ESLint 檢查編碼規(guī)范；
• 用 Prettier 插件自動保存為規(guī)劃化格式；
• 用 Commitizen 約定提交規(guī)范；

動手解決

本文案例運行環(huán)境和編輯器

• node ^16.13.1
• npm ^8.1.2
• @vue/cli ^4.5.15
• 使用了 VS Code 編輯器

我會用 vue-cli 創(chuàng)建一個 Vue 項目做示范，React 項目的做法其實也差不多的。
接下來的代碼、語法基本不會依賴 vue，因為本文是講代碼規(guī)范和 Git 提交規(guī)范。

1、創(chuàng)建項目

1.1、使用 vue-cli 創(chuàng)建項目

沒安裝 vue-cli 的同學可以使用這條命令安裝一下。

npm install -g @vue/cli

然后使用 vue-cli 創(chuàng)建項目。

# 【第1步】 使用命令創(chuàng)建項目
vue create 項目名（小寫英文）

######################################################

# 【第2步】 選擇模板
? Please pick a preset: Manually select features
Vue CLI v4.5.15
? Please pick a preset: (Use arrow keys)
  Default ([Vue 2] babel, eslint)
  Default (Vue 3) ([Vue 3] babel, eslint)
> Manually select features  # 選擇這項，手動匹配

######################################################

# 【第3步】 選擇需要的功能。請根據(jù)自己的項目選擇，本文只做代碼規(guī)范，所以vuex、路由、css預處理器這些我都沒選。
? Check the features needed for your project: (Press <space> to select, <a> to toggle all, <i> to invert selection)
 (*) Choose Vue version
 (*) Babel
 ( ) TypeScript
 ( ) Progressive Web App (PWA) Support
 ( ) Router
 ( ) Vuex
 ( ) CSS Pre-processors
>(*) Linter / Formatter  # 代碼格式化，記得選上這個！
 ( ) Unit Testing
 ( ) E2E Testing
 
######################################################

# 【第4步】 選擇Vue版本。本文使用了 3.x。
? Choose a version of Vue.js that you want to start the project with
  2.x
> 3.x

######################################################

# 【第5步】 選擇規(guī)范方案。vue-cli默認提供了幾套規(guī)范，我選擇了 ESLint 標準規(guī)范
? Pick a linter / formatter config:
  ESLint with error prevention only
  ESLint + Airbnb config
> ESLint + Standard config  # ESLint 標準規(guī)范方案
  ESLint + Prettier

######################################################

# 【第6步】 選擇檢測代碼規(guī)范的操作（保存時，提交時），這里我都選上了。
? Pick additional lint features: (Press <space> to select, <a> to toggle all, <i> to invert selection)
 (*) Lint on save  # 保存時檢測
>(*) Lint and fix on commit  # 提交時檢測

######################################################

# 【第7步】 你更喜歡把Babel, ESLint等配置放在哪里?  
? Where do you prefer placing config for Babel, ESLint, etc.? (Use arrow keys)
> In dedicated config files  # 單獨的配置文件
  In package.json

######################################################

# 【第7步】 將此保存為未來項目的預設? 我選在不需要：n
? Save this as a preset for future projects? (y/N) n

經(jīng)過漫長的等待，項目就創(chuàng)建成功了。

運行項目：

cd 項目目錄
npm run serve

2、配置 ESLint 規(guī)則

ESLint 是代碼檢測工具，在上一步創(chuàng)建項目的操作中，我們已經(jīng)把 ESLint 集成在項目中了。

不太清除 ESLint 的同學可以看官網(wǎng)介紹：『ESLint』

2.1 配置

打開 根目錄 下的 .eslintrc.js 文件可以看到默認的配置項。

module.exports = {
  root: true, // 當前文件是否在項目的根目錄
  env: { // 啟用 ESLint 檢測的環(huán)境
    node: true // 在 node 環(huán)境下啟動 ESLint 檢測
  },
  extends: [ // 需要繼承的基礎配置項
    'plugin:vue/vue3-essential',
    '@vue/standard'
  ],
  parserOptions: { // 指明解析器
    parser: 'babel-eslint'
  },
  /*
   * 這里非常重要，項目的主要配置規(guī)則是寫在這里的?。。。。?！
   * 比如：在項目中是否允許使用 console ？ 是否允許使用雙引號包裹字符串？……
   *
   * "off" 或 0 - 關閉規(guī)則
   * "warn" 或 1 - 開啟規(guī)則，使用警告級別的錯誤：warn (不會導致程序退出)
   * "error" 或 2 - 開啟規(guī)則，使用錯誤級別的錯誤：error (當被觸發(fā)的時候，程序會退出)
   */
  rules: {
    'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'warn' : 'off',
    'space-before-function-paren': 'off'
  }
}

2.2 測試

現(xiàn)在的項目在 JS 里默認使用單引號包裹字符串，此時如果使用雙引號就會報錯。

可以嘗試修改一下 App.vue

/* 省略部分代碼 */
<script>
export default {
  name: "App"  // 此時這里使用了雙引號
}
</script>

當使用雙引號包裹字符串時，ESLint 就會提示如下錯誤

E:\practice\vue\vue3\vue3-demo1\src\App.vue
  10:9  error  Strings must use singlequote  quotes

? 1 problem (1 error, 0 warnings)
  1 error and 0 warnings potentially fixable with the `--fix` option.

會提示出現(xiàn)錯誤的文件，行數(shù)，列數(shù)。然后給出一個提示錯誤 Strings must use singlequote quotes ，意思是 “字符串必須使用單引號”。

如果你的團隊是習慣使用雙引號，習慣在語句后面加分號，這些配置可以百度查查，本文不打算在 編碼規(guī)范 上深入講解，因為每個團隊的風格不同。

3、安裝代碼格式化插件 Prettier

Prettier 能自動幫你按規(guī)范格式化代碼。 『Prettier 中文網(wǎng)』

3.1 安裝 Prettier

很多時候你的編碼風格已經(jīng)形成習慣了，進入新團隊后一下子難以改過來，如果經(jīng)常出現(xiàn) 編碼規(guī)范 的錯誤提醒真的很影響開發(fā)速度。

此時 Prettier 就可以幫到你了。Prettier 可以在你保存時，根據(jù)你設置好的規(guī)則自動格式化代碼。

file

我主要使用 VS Code 這款編輯器，所以可以直接在插件市場里找到 Prettier ，直接點擊安裝即可。

3.2 配置方案

裝好 Prettier 插件后，就可以根據(jù)你項目規(guī)范的需求配置 自動格式化方案 了。

在項目 根目錄 下創(chuàng)建 .prettierrc 文件，這個文件就是告訴 Prettier 怎么格式化代碼的。

里面可以寫如下配置：

{
  // 不使用分號語法
  "semi": false,
  // 使用單引號
  "singleQuote": true,
  // 對象最后一行不加逗號
  "trailingComma": "none"
}

更多配置可以百度，也可以在 『Prettier 中文網(wǎng)』 查閱。

3.3 設置保存時自動格式化代碼

打開 VS Code 設置面板：文件 - 首選項 - 設置

file

然后在搜索欄輸入 save ，之后勾選上 Editor: Format On Save 即可。

file

需要注意的是，如果配置完 ESLint 或 Prettier 不生效的話，請重新運行一下項目。

4、約定式提交規(guī)范

git commit 也要做到規(guī)范化，最好提供模板的方式提交。

4.1 好的規(guī)范！

前面講的都是 編碼時 的規(guī)范約束，其實還有另一個規(guī)范是很多人沒注意到的，它就是 版本信息 規(guī)范。

先來看看什么叫 好的規(guī)范：

file

每個記錄都有功能說明，然后再簡單描述一下本次提交的說明。

4.2 遇到的問題

上面的例子看上去是很舒服，但每次這樣寫會不會很麻煩？如何保證每個人都按同一個規(guī)范來寫？比如：有人寫“修復bug”，有人寫“修復漏洞”。

4.3 解決方法

使用“約定式提交規(guī)范”。

所謂的 約定式提交規(guī)范 其實就是提供一套模板讓你選擇本次提交的大概方向，最后再簡單寫上一兩句本次提交說明即可。

約定式提交規(guī)范 被討論得最多的就是的 Angular團隊規(guī)范 延伸出的 Conventional Commits specification（約定式提交） 。有興趣可以看看。

約定式提交規(guī)范格式：

<type>[optional scope]: <description>

<類型>[可選 范圍]: <描述>

類型是一堆選項，不需要用戶手動輸入。這樣就可以解決上面提到的其中一個問題。

4.4 動手實現(xiàn)

用 Commitizen 和 cz-customizable 來實現(xiàn)。并且使用 git cz 來代替 git commit 。

4.4.1 安裝

npm install commitizen cz-customizable -dev

使用上面這條命令就可以安裝 commitizen 和 cz-customizable。

這里之所以不全局安裝 -g ，是因為新接手項目的伙伴可能自己電腦本身沒安裝 commitizen。此時跟著項目中安裝他也可以正常使用。

如果你是經(jīng)常使用這種規(guī)范話提交的，建議你全局安裝 commitizen。

但 cz-customizable 還是建議安裝在項目中 -dev ，這樣可以方便每個項目獨立配置。

4.4.2 配置

在 package.json 中添加以下配置：

/* 省略部分代碼 */
"config": {
  "commitizen": {
    "path": "node_modules/cz-customizable"
  }
}

在項目根目錄下創(chuàng)建 .cz-config.js 文件，并添加以下配置：

module.exports = {
  // 可選類型
  types: [
    { value: 'feat', name: '? feat: 新功能' },
    { value: 'fix', name: '?? fix: 修復Bug' },
    { value: 'docs', name: '?? docs: 文檔變更' },
    { value: 'style', name: '?? style: 不影響代碼含義的變化(空白、格式化、缺少分號等)' },
    { value: 'refactor', name: '?? refactor: 重構代碼，既不修復錯誤也不添加功能' },
    { value: 'perf', name: '? perf: 性能優(yōu)化' },
    { value: 'test', name: '? test: 測試相關' },
    { value: 'ci', name: '?? ci: 更改持續(xù)集成文件和腳本' },
    { value: 'chore', name: '?? chore: 重新打包或更新依賴工具等雜活' },
    { value: 'revert', name: '? revert: 代碼回退' },
    { value: 'WIP', name: '?? WIP: Work in progress' }
  ],
  // scope 類型（定義之后，可通過上下鍵選擇）
  scopes: [
    ['components', '組件相關'],
    ['hooks', 'hook 相關'],
    ['utils', 'utils 相關'],
    ['element-ui', '對 element-ui 的調(diào)整'],
    ['styles', '樣式相關'],
    ['deps', '項目依賴'],
    ['config', '配置相關'],
    ['other', '其他修改'],
    // 如果選擇 custom，后面會讓你再輸入一個自定義的 scope。也可以不設置此項，把后面的 allowCustomScopes 設置為 true
    ['custom', '以上都不是？我要自定義']
  ].map(([value, description]) => {
    return {
      value,
      name: `${value.padEnd(30)} (${description})`
    }
  }),

  // 步驟消息提示
  messages: {
    type: '確保本次提交遵循規(guī)范！\n選擇你要提交的類型：',
    scope: '\n選擇一個 scope（可選）：',
    customScope: '請輸入修改范圍（可選）：',
    subject: '請輸入變更描述（必填）：',
    body: '填寫更加詳細的變更描述（可選）：',
    footer: '請輸入要關閉的 ISSUES （可選）：',
    confirmCommit: '確認提交？'
  },
  // 允許自定義范圍
  allowCustomScopes: true,
  // 要跳過的問題
  skipQuestions: ['footer'],

  // subject文字默認值是72
  subjectLimit: 100
}

4.4.3 使用

此時就可以使用 git cz 來代替 git commit 了。

經(jīng)過上面的配置后，可以使用 git add . 把變更內(nèi)容提交到暫存區(qū)，然后再使用 git cz 提交一次版本。

git add .

git cz

輸入完 git cz 后，就開始選擇提交的類型

file

選擇變更的范圍

file

之后還會有一系列的提示，部分是規(guī)定必填的。

file

最后確認提交，就可以生成一個版本。

file

最后使用 git log 可以查看提交的歷史記錄。

file

規(guī)范參考

airbnb規(guī)范

google規(guī)范

百度EFE規(guī)范

京東Aotu規(guī)范

JS代碼備注規(guī)范：JSDoc

阮一峰的 Commit message 和 Change log 編寫指南

如果本文對你有幫助，請幫我點個贊吧，同時你也可以把本文推薦給你的朋友。

點贊 + 關注 + 收藏 = 學會了