一、編程規(guī)范

(一)命名規(guī)范

1.1.1 項(xiàng)目命名

全部采用小寫方式， 以中劃線分隔。

正例：mall-management-system

反例：mall_management-system / mallManagementSystem

1.1.2 目錄命名

全部采用小寫方式， 以中劃線分隔，有復(fù)數(shù)結(jié)構(gòu)時(shí)，要采用復(fù)數(shù)命名法， 縮寫不用復(fù)數(shù)

正例： scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc

反例： script / style / demo_scripts / demoStyles / imgs / docs

【特殊】VUE 的項(xiàng)目中的 components 中的組件目錄，使用 kebab-case 命名

正例： head-search / page-loading / authorized / notice-icon

反例： HeadSearch / PageLoading

【特殊】VUE 的項(xiàng)目中的除 components 組件目錄外的所有目錄也使用 kebab-case 命名

正例： page-one / shopping-car / user-management

反例： ShoppingCar / UserManagement

1.1.3 JS、CSS、SCSS、HTML、PNG 文件命名

全部采用小寫方式， 以中劃線分隔

正例： render-dom.js / signup.css / index.html / company-logo.png

反例： renderDom.js / UserManagement.html

1.1.4 命名嚴(yán)謹(jǐn)性

代碼中的命名嚴(yán)禁使用拼音與英文混合的方式，更不允許直接使用中文的方式。 說明：正確的英文拼寫和語法可以讓閱讀者易于理解，避免歧義。注意，即使純拼音命名方式也要避免采用

正例：henan / luoyang / rmb 等國際通用的名稱，可視同英文。

反例：DaZhePromotion [打折] / getPingfenByName() [評(píng)分] / int 某變量 = 3

杜絕完全不規(guī)范的縮寫，避免望文不知義：

反例：AbstractClass“縮寫”命名成 AbsClass；condition“縮寫”命名成 condi，此類隨意縮寫嚴(yán)重降低了代碼的可閱讀性。

(二) CSS 規(guī)范

1.2.1 命名

類名使用小寫字母，以中劃線分隔

id 采用駝峰式命名

scss 中的變量、函數(shù)、混合、placeholder 采用駝峰式命名

ID 和 class 的名稱總是使用可以反應(yīng)元素目的和用途的名稱，或其他通用的名稱，代替表象和晦澀難懂的名稱

不推薦：

.fw-800 {

? font-weight: 800;

}

.red {

? color: red;

}

推薦:

.heavy {

? font-weight: 800;

}

.important {

? color: red;

}

1.2.2 選擇器

1、css 選擇器中避免使用標(biāo)簽名從結(jié)構(gòu)、表現(xiàn)、行為分離的原則來看，應(yīng)該盡量避免 css 中出現(xiàn) HTML 標(biāo)簽，并且在 css 選擇器中出現(xiàn)標(biāo)簽名會(huì)存在潛在的問題。

2、很多前端開發(fā)人員寫選擇器鏈的時(shí)候不使用 直接子選擇器（注：直接子選擇器和后代選擇器的區(qū)別）。有時(shí)，這可能會(huì)導(dǎo)致疼痛的設(shè)計(jì)問題并且有時(shí)候可能會(huì)很耗性能。然而，在任何情況下，這是一個(gè)非常不好的做法。如果你不寫很通用的，需要匹配到 DOM 末端的選擇器， 你應(yīng)該總是考慮直接子選擇器。

不推薦:

.content .title {

? font-size: 2rem;

}

推薦:

.content > .title {

? font-size: 2rem;

}

1.2.3 省略0后面的單位

不推薦：

div{

? padding-bottom: 0px;

? margin: 0em;

}

推薦：

div{

? padding-bottom: 0;

? margin: 0;

}

(三) js 規(guī)范

1、條件判斷和循環(huán)最多三層

條件判斷能使用三目運(yùn)算符和邏輯運(yùn)算符解決的，就不要使用條件判斷，但是謹(jǐn)記不要寫太長的三目運(yùn)算符。如果超過 3 層請抽成函數(shù)，并寫清楚注釋。

2、this 的轉(zhuǎn)換命名

對上下文 this 的引用只能使用'self'來命名

3、undefined 判斷

永遠(yuǎn)不要直接使用 undefined 進(jìn)行變量判斷；使用 typeof 和字符串'undefined'對變量進(jìn)行判斷。

正例：

if (typeof person === 'undefined') {

? ? ...

}

反例：

if (person === undefined) {

? ? ...

}

二、Vue 項(xiàng)目規(guī)范

(一) Vue 編碼基礎(chǔ)

vue 項(xiàng)目規(guī)范以 Vue 官方規(guī)范 （?https://cn.vuejs.org/v2/style-guide/?） 中的 A 規(guī)范為基礎(chǔ)，在其上面進(jìn)行項(xiàng)目開發(fā)，故所有代碼均遵守該規(guī)范。

請仔仔細(xì)細(xì)閱讀 Vue 官方規(guī)范，切記，此為第一步。

2.1.1、 組件名為多個(gè)單詞。

組件名應(yīng)該始終是多個(gè)單詞組成（大于等于 2），且命名規(guī)范為KebabCase格式。

這樣做可以避免跟現(xiàn)有的以及未來的 HTML 元素相沖突，因?yàn)樗械?HTML 元素名稱都是單個(gè)單詞的。

正例：

export default {

? name: 'TodoItem'

? // ...

};

反例：

export default {

? name: 'Todo',

? // ...

}

export default {

? name: 'todo-item',

? // ...

}

2.1.2、組件文件名為 pascal-case 格式

正例：

components/

|- my-component.vue

反例：

components/

|- myComponent.vue

|- MyComponent.vue

2.1.3、基礎(chǔ)組件文件名為 base 開頭，使用完整單詞而不是縮寫。

正例：

components/

|- base-button.vue

|- base-table.vue

|- base-icon.vue

反例：

components/

|- MyButton.vue

|- VueTable.vue

|- Icon.vue

2.1.4、和父組件緊密耦合的子組件應(yīng)該以父組件名作為前綴命名

正例：

components/

|- todo-list.vue

|- todo-list-item.vue

|- todo-list-item-button.vue

|- user-profile-options.vue （完整單詞）

反例：

components/

|- TodoList.vue

|- TodoItem.vue

|- TodoButton.vue

|- UProfOpts.vue （使用了縮寫）

2.1.5、在 Template 模版中使用組件，應(yīng)使用 PascalCase 模式，并且使用自閉合組件。

正例：

<!-- 在單文件組件、字符串模板和 JSX 中 -->

<MyComponent />

<Row><table :column="data"/></Row>

反例：

<my-component /> <row><table :column="data"/></row>

2.1.6、組件的 data 必須是一個(gè)函數(shù)

當(dāng)在組件中使用 data 屬性的時(shí)候 (除了 new Vue 外的任何地方)，它的值必須是返回一個(gè)對象的函數(shù)。 因?yàn)槿绻苯邮且粋€(gè)對象的話，子組件之間的屬性值會(huì)互相影響。

正例：

export default {

? data () {

? ? return {

? ? ? name: 'jack'

? ? }

? }

}

反例：

export default {

? data: {

? ? name: 'jack'

? }

}

2.1.7、 Prop 定義應(yīng)該盡量詳細(xì)

·?必須使用 camelCase 駝峰命名

·?必須指定類型

·?必須加上注釋，表明其含義

·?必須加上 required 或者 default，兩者二選其一

·?如果有業(yè)務(wù)需要，必須加上 validator 驗(yàn)證

正例：

props: {

? // 組件狀態(tài)，用于控制組件的顏色

? status: {

? ? type: String,

? ? required: true,

? ? validator: function (value) {

? ? ? return [

? ? ? ? 'succ',

? ? ? ? 'info',

? ? ? ? 'error'

? ? ? ].indexOf(value) !== -1

? ? }

? },

? ? // 用戶級(jí)別，用于顯示皇冠個(gè)數(shù)

? userLevel：{

? ? ? type: String,

? ? ? required: true

? }

}

2.1.8、為組件樣式設(shè)置作用域

正例：

<template>

? <button class="btn btn-close">X</button>

</template>

<!-- 使用 `scoped` 特性 -->

<style scoped>

? .btn-close {

? ? background-color: red;

? }

</style>

反例：

<template>

? <button class="btn btn-close">X</button>

</template>

<!-- 沒有使用 `scoped` 特性 -->

<style>

? .btn-close {

? ? background-color: red;

? }

</style>

(二) Vue

2.2.1 基礎(chǔ)

vue 項(xiàng)目中的所有命名一定要與后端命名統(tǒng)一。

比如權(quán)限：后端 privilege, 前端無論 router , store, api 等都必須使用 privielege 單詞！

2.2.2 使用 Vue-cli 腳手架

使用 vue-cli3 來初始化項(xiàng)目，項(xiàng)目名按照上面的命名規(guī)范。

2.2.3 目錄說明

目錄名按照上面的命名規(guī)范，其中 components 組件用大寫駝峰，其余除 components 組件目錄外的所有目錄均使用 kebab-case 命名。

src? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 源碼目錄

|-- api? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 所有api接口

|-- assets? ? ? ? ? ? ? ? ? ? ? ? ? 靜態(tài)資源，images, icons, styles等

|-- components? ? ? ? ? ? ? ? ? ? ? 公用組件

|-- config? ? ? ? ? ? ? ? ? ? ? ? ? 配置信息

|-- constants? ? ? ? ? ? ? ? ? ? ? ? 常量信息，項(xiàng)目所有Enum, 全局常量等

|-- directives? ? ? ? ? ? ? ? ? ? ? 自定義指令

|-- filters? ? ? ? ? ? ? ? ? ? ? ? ? 過濾器，全局工具

|-- datas? ? ? ? ? ? ? ? ? ? ? ? ? ? 模擬數(shù)據(jù)，臨時(shí)存放

|-- lib? ? ? ? ? ? ? ? ? ? ? ? ? ? ? 外部引用的插件存放及修改文件

|-- mock? ? ? ? ? ? ? ? ? ? ? ? ? ? 模擬接口，臨時(shí)存放

|-- plugins? ? ? ? ? ? ? ? ? ? ? ? ? 插件，全局使用

|-- router? ? ? ? ? ? ? ? ? ? ? ? ? 路由，統(tǒng)一管理

|-- store? ? ? ? ? ? ? ? ? ? ? ? ? ? vuex, 統(tǒng)一管理

|-- themes? ? ? ? ? ? ? ? ? ? ? ? ? 自定義樣式主題

|-- views? ? ? ? ? ? ? ? ? ? ? ? ? ? 視圖目錄

|? |-- role? ? ? ? ? ? ? ? ? ? ? ? ? ? role模塊名

|? |-- |-- role-list.vue? ? ? ? ? ? ? ? ? ? role列表頁面

|? |-- |-- role-add.vue? ? ? ? ? ? ? ? ? ? role新建頁面

|? |-- |-- role-update.vue? ? ? ? ? ? ? ? ? role更新頁面

|? |-- |-- index.less? ? ? ? ? ? ? ? ? ? ? role模塊樣式

|? |-- |-- components? ? ? ? ? ? ? ? ? ? ? role模塊通用組件文件夾

|? |-- employee? ? ? ? ? ? ? ? ? ? ? ? employee模塊

1、api 目錄

·?文件、變量命名要與后端保持一致。

·?此目錄對應(yīng)后端 API 接口，按照后端一個(gè) controller 一個(gè) api js 文件。若項(xiàng)目較大時(shí)，可以按照業(yè)務(wù)劃分子目錄，并與后端保持一致。

·?api 中的方法名字要與后端 api url 盡量保持語義高度一致性。

·?對于 api 中的每個(gè)方法要添加注釋，注釋與后端 swagger 文檔保持一致。

正例：

后端 url： EmployeeController.java

/employee/add

/employee/delete/{id}

/employee/update

前端： employee.js

? // 添加員工

? addEmployee: (data) => {

? ? return postAxios('/employee/add', data)

? },

? // 更新員工信息

? updateEmployee: (data) => {

? ? return postAxios('/employee/update', data)

? },

? ? // 刪除員工

? deleteEmployee: (employeeId) => {

? ? return postAxios('/employee/delete/' + employeeId)

? }

2、 assets 目錄

assets 為靜態(tài)資源，里面存放 images, styles, icons 等靜態(tài)資源，靜態(tài)資源命名格式為 kebab-case

|assets

|-- icons

|-- images

|? |-- background-color.png

|? |-- upload-header.png

|-- styles

3、 components 目錄

此目錄應(yīng)按照組件進(jìn)行目錄劃分，目錄命名為 KebabCase，組件命名規(guī)則也為 KebabCase

|components

|-- error-log

|? |-- index.vue

|? |-- index.less

|-- markdown-editor

|? |-- index.vue

|? |-- index.js

|-- kebab-case

4、 constants 目錄

此目錄存放項(xiàng)目所有常量，如果常量在 vue 中使用，請使用 vue-enum 插件(https://www.npmjs.com/package/vue-enum)

目錄結(jié)構(gòu)：

|constants

|-- index.js

|-- role.js

|-- employee.js

例子： employee.js

export const EMPLOYEE_STATUS = {

? NORMAL: {

? ? value: 1,

? ? desc: '正常'

? },

? DISABLED: {

? ? value: 1,

? ? desc: '禁用'

? },

? DELETED: {

? ? value: 2,

? ? desc: '已刪除'

? }

};

export const EMPLOYEE_ACCOUNT_TYPE = {

? QQ: {

? ? value: 1,

? ? desc: 'QQ登錄'

? },

? WECHAT: {

? ? value: 2,

? ? desc: '微信登錄'

? },

? DINGDING: {

? ? value: 3,

? ? desc: '釘釘?shù)卿?

? },

? USERNAME: {

? ? value: 4,

? ? desc: '用戶名密碼登錄'

? }

};

export default {

? EMPLOYEE_STATUS,

? EMPLOYEE_ACCOUNT_TYPE

};

5、router 與 store 目錄

這兩個(gè)目錄一定要將業(yè)務(wù)進(jìn)行拆分，不能放到一個(gè) js 文件里。

router 盡量按照 views 中的結(jié)構(gòu)保持一致

store 按照業(yè)務(wù)進(jìn)行拆分不同的 js 文件

6、 views 目錄

·?命名要與后端、router、api 等保持一致

·?components 中組件要使用 PascalCase 規(guī)則

|-- views? ? ? ? ? ? ? ? ? ? ? ? ? ? 視圖目錄

|? |-- role? ? ? ? ? ? ? ? ? ? ? ? ? ? role模塊名

|? |? |-- role-list.vue? ? ? ? ? ? ? ? ? ? role列表頁面

|? |? |-- role-add.vue? ? ? ? ? ? ? ? ? ? role新建頁面

|? |? |-- role-update.vue? ? ? ? ? ? ? ? ? role更新頁面

|? |? |-- index.less? ? ? ? ? ? ? ? ? ? ? role模塊樣式

|? |? |-- components? ? ? ? ? ? ? ? ? ? ? role模塊通用組件文件夾

|? |? |? |-- role-header.vue? ? ? ? ? ? ? ? ? ? ? ? role頭部組件

|? |? |? |-- role-modal.vue? ? ? ? ? ? ? ? ? ? ? ? role彈出框組件

|? |-- employee? ? ? ? ? ? ? ? ? ? ? ? employee模塊

|? |-- behavior-log? ? ? ? ? ? ? ? ? ? ? 行為日志log模塊

|? |-- code-generator? ? ? ? ? ? ? ? ? ? 代碼生成器模塊

2.2.4 注釋說明

整理必須加注釋的地方

公共組件使用說明

·?api 目錄的接口 js 文件必須加注釋

·?store 中的 state, mutation, action 等必須加注釋

·?vue 文件中的 template 必須加注釋，若文件較大添加 start end 注釋

·?vue 文件的 methods，每個(gè) method 必須添加注釋

·?vue 文件的 data, 非常見單詞要加注釋

注釋規(guī)范

代碼注釋在一個(gè)項(xiàng)目的后期維護(hù)中顯的尤為重要，所以我們要為每一個(gè)被復(fù)用的組件編寫組件使用說明，為組件中每一個(gè)方法編寫方法說明

務(wù)必添加注釋列表

1、公共組件使用說明

2、各組件中重要函數(shù)或者類說明

3、復(fù)雜的業(yè)務(wù)邏輯處理說明

4、特殊情況的代碼處理說明,對于代碼中特殊用途的變量、存在臨界值、函數(shù)中使用的 hack、使用了某種算法或思路等需要進(jìn)行注釋描述

5、多重 if 判斷語句

6、注釋塊必須以/（至少兩個(gè)星號(hào)）開頭/

7、單行注釋使用 //

單行注釋

注釋單獨(dú)一行，不要在代碼后的同一行內(nèi)加注釋。例如：

? bad

? var name =”abc”; // 姓名

? good

? // 姓名

? var name = “abc”;

多行注釋

組件使用說明，和調(diào)用說明

? ? ? /**

? ? ? * 組件名稱

? ? ? * @module 組件存放位置

? ? ? * @desc 組件描述

? ? ? * @author 組件作者

? ? ? * @date 2017年12月05日17:22:43

? ? ? * @param {Object} [title]? ? - 參數(shù)說明

? ? ? * @param {String} [columns] - 參數(shù)說明

? ? ? * @example 調(diào)用示例

? ? ? *? <hbTable :title="title" :columns="columns" :tableData="tableData"></hbTable>

? ? ? **/