一、編程規(guī)范

(一)命名規(guī)范

1.1.1 項目命名

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

正例：mall-management-system

反例：mall_management-system / mallManagementSystem

1.1.2 目錄命名

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

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

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

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

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

反例： HeadSearch / PageLoading

【特殊】VUE 的項目中的除 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 命名嚴謹性

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

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

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

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

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

(二) CSS 規(guī)范

1.2.1 命名

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

id 采用駝峰式命名

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

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

不推薦：

.fw-800 {

? font-weight: 800;

}

.red {

? color: red;

}

推薦:

.heavy {

? font-weight: 800;

}

.important {

? color: red;

}

1.2.2 選擇器

1、css 選擇器中避免使用標簽名從結構、表現(xiàn)、行為分離的原則來看，應該盡量避免 css 中出現(xiàn) HTML 標簽，并且在 css 選擇器中出現(xiàn)標簽名會存在潛在的問題。

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

不推薦:

.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)最多三層

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

2、this 的轉換命名

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

3、undefined 判斷

永遠不要直接使用 undefined 進行變量判斷；使用 typeof 和字符串'undefined'對變量進行判斷。

正例：

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

? ? ...

}

反例：

if (person === undefined) {

? ? ...

}

二、Vue 項目規(guī)范

(一) Vue 編碼基礎

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

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

2.1.1、 組件名為多個單詞。

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

這樣做可以避免跟現(xiàn)有的以及未來的 HTML 元素相沖突，因為所有的 HTML 元素名稱都是單個單詞的。

正例：

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、基礎組件文件名為 base 開頭，使用完整單詞而不是縮寫。

正例：

components/

|- base-button.vue

|- base-table.vue

|- base-icon.vue

反例：

components/

|- MyButton.vue

|- VueTable.vue

|- Icon.vue

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

正例：

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 模版中使用組件，應使用 PascalCase 模式，并且使用自閉合組件。

正例：

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

<MyComponent />

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

反例：

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

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

當在組件中使用 data 屬性的時候 (除了 new Vue 外的任何地方)，它的值必須是返回一個對象的函數(shù)。 因為如果直接是一個對象的話，子組件之間的屬性值會互相影響。

正例：

export default {

? data () {

? ? return {

? ? ? name: 'jack'

? ? }

? }

}

反例：

export default {

? data: {

? ? name: 'jack'

? }

}

2.1.7、 Prop 定義應該盡量詳細

·?必須使用 camelCase 駝峰命名

·?必須指定類型

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

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

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

正例：

props: {

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

? status: {

? ? type: String,

? ? required: true,

? ? validator: function (value) {

? ? ? return [

? ? ? ? 'succ',

? ? ? ? 'info',

? ? ? ? 'error'

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

? ? }

? },

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

? userLevel：{

? ? ? type: String,

? ? ? required: true

? }

}

2.1.8、為組件樣式設置作用域

正例：

<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 基礎

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

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

2.2.2 使用 Vue-cli 腳手架

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

2.2.3 目錄說明

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

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

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

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

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

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

|-- constants? ? ? ? ? ? ? ? ? ? ? ? 常量信息，項目所有Enum, 全局常量等

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

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

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

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

|-- mock? ? ? ? ? ? ? ? ? ? ? ? ? ? 模擬接口，臨時存放

|-- 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 目錄

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

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

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

·?對于 api 中的每個方法要添加注釋，注釋與后端 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 目錄

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

|components

|-- error-log

|? |-- index.vue

|? |-- index.less

|-- markdown-editor

|? |-- index.vue

|? |-- index.js

|-- kebab-case

4、 constants 目錄

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

目錄結構：

|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 目錄

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

router 盡量按照 views 中的結構保持一致

store 按照業(yè)務進行拆分不同的 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，每個 method 必須添加注釋

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

注釋規(guī)范

代碼注釋在一個項目的后期維護中顯的尤為重要，所以我們要為每一個被復用的組件編寫組件使用說明，為組件中每一個方法編寫方法說明

務必添加注釋列表

1、公共組件使用說明

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

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

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

5、多重 if 判斷語句

6、注釋塊必須以/（至少兩個星號）開頭/

7、單行注釋使用 //

單行注釋

注釋單獨一行，不要在代碼后的同一行內加注釋。例如：

? bad

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

? good

? // 姓名

? var name = “abc”;

多行注釋

組件使用說明，和調用說明

? ? ? /**

? ? ? * 組件名稱

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

? ? ? * @desc 組件描述

? ? ? * @author 組件作者

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

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

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

? ? ? * @example 調用示例

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

? ? ? **/