面試官:談談你們專案當中的前端程式碼規範吧?
自己先想一分鐘。
前面的話
首先我想說的是,這篇文章不是介紹什麼高深的技術,請各位熟知。涉及的都是日常開發當中一些不符合規範的案例,藉此分享給諸位。如果你是小白,或許這篇文章對你有點幫助,如果你是老司機,看完請輕點拍!有什麼建議或意見請留言斧正,謝謝!
有些同學在開發某個新功能時根據需求就哐哐哐(按照自己的程式碼風格)一頓擼。寫完發現,另一個地方也有這個模組功能,可能只是標題的顏色,字型大小不對。怎麼辦? 於是很雞賊的複製貼上過去,改吧改吧,提交程式碼,萬事大吉!自己倒是爽了,功能是按照需求如期完成了啊,沒毛病。可是你卻忽視了一件很重要的東西:團隊。
記住,你不是一個人在寫程式碼。
這篇文章有別於其他教程類的文章,不是教你如何制定程式碼規範,也不是告訴你這樣寫就是錯的亦或說是正確的。本文是我這些天從優化別人程式碼過程中的所見和所得,凝結成文。旨在分享給大家,對號入座,然後改之。三人行,必有我師!;擇其善者而從之,其不善者而改之。 由於我是做前端的,所以只說前端程式碼規範,其他語言同樣適用!
目的
把一些常見的錯誤的不良的程式碼示例分享給大家,希望有的改之,無則加勉。看完之後,希望對你們有所幫助,提高自己的程式碼質量,每個人都能寫出一手漂亮的程式碼。這是這篇文章最大的目的了!
概述
本文將以我的親身專案經歷為例,來談談我們日常開發當中,就程式碼層面來講,我們應該注意的一些小細節。希望各位看客能吸取精華去其糟粕。主要涉及的方面有:
- 專案結構
- 檔案命名
- 路由
- Vue 元件
- JavaScript
- Html
- Css
- Git 程式碼提交
我將會從以上幾個方面逐一列舉和大家分享討論。
列舉
1. 專案結構
沒說之前,您不妨看下自己的專案結構是什麼樣的。目前我們的專案結構是這樣的:
my-project
├── .idea # 這個是編輯器生成的
├── build # Webpack 配置檔案放在這裡
├── config # Vue 基本配置檔案放在這裡
├── node_modules # 第三方依賴
├── src # 專案原始碼(核心檔案)
│ ├── assets # 資原始檔(js, css, scss)
│ ├── components # 所有元件
│ ├── js # 自己寫的 js,裡面各種工具類方法等
│ ├── mixins # 混合
│ ├── router # 路由
│ ├── vuex # 狀態管理
│ ├── App.vue # 根元件
│ └── main.js # 入口檔案
├── static # 靜態資源,一般放 img
├── theme # 主題檔案,修改的 Element-UI 主題
├── .babelrc # babel 編譯配置
├── .editorconfig # 程式碼格式
├── .gitignore # Git 提交忽略的檔案配置
├── .postcssrc.js # 轉換 css 的工具配置檔案
├── element-variables.css # Element 全域性定義的變數,不明白為啥放這兒
├── index.html # 主頁模板
├── package-lock.json # 用來鎖定依賴的版本號(NPM 自動生成)
├── package.json # 專案基本資訊
└── README.md # 專案介紹
複製程式碼
都是用 vue-cli 生成的,目錄結構和命名規範也就沒啥可說的。可能隨著時間的推移,自己會在專案里加一些東西(檔案或資料夾)。拿上面我們的專案為例來說幾點吧:
- 根目錄下不要有 css 檔案:
比如 element-variables.css
檔案,雖然這個檔案是 Element自定義主題 自動生產的,但是可以通過配置更換生成所在目錄。因為它屬於 theme
資料夾下的東西,所以應該放它下面的。
js
資料夾應該命名為utils
:
因為它對外暴露的都是工具類方法,這樣更顯語義化。
關於專案結構,我發現的就這麼多。每個專案的目錄可能會不同,這個就看你們的規範了。
2. 檔案的命名
它包含檔案的命名和資料夾的命名。依我們的專案為例,我重點說下 src/components
目錄下的命名,真的是五花八門:
2.1. 檔名不夠語義化
這個還算正常,但還是有些問題。這裡是一些問題清單:- 這個模組的中文叫,是關於機器人學習的,叫
knowledgeBaseManagement
雖然很好的翻譯了中文意思,但總覺的有點長,叫robot
會不會好些? - 而且資料夾下的檔案命名也不夠語義化
下面是整理過後的樣子:
robot
├── addQuestion.vue
├── editQuestion.vue
├── index.vue
└── missedQuestion.vue
複製程式碼
這個我就不想說了,看的我頭皮發麻。從字面意思上來講,我就認識一個 TreeNode2.vue
。後面還加個 2 是什麼鬼?
2.2. 檔案目錄不統一
這屬於一類問題,即裡面太亂了,不統一,問題清單:
src/components/moduleName/
下除了子模組外,儘量不要瞎放其他無關的資料夾,如上面的src
、component/common
、top
callcenterList/src
下的圖片可以放到static
下- 如果是功能型元件(上面的
color
是一個顏色選擇器元件),儘量放到一個叫package
或者lib
的資料夾下。因為src/components
下的模組都是系統模組,不要混淆。 elvesSetting/top
如果是某幾個頁面頭部的公共部分儘量放到components/common
下
2.3. 檔名過長
如果一個模組下就一個檔案,儘量寫成 index.vue
。這裡資料夾和檔案同名,路由是不是很長?你在其他檔案中 import
的時候是不是也不方便? 而且我發現 problemManagement
和 problemRetrieve
都屬於問題管理模組,完全可以合併到一個資料夾裡啊。還有,資料夾已經表明是問題管理模組了,所以檔名就不要再以 problem***
開頭了。不覺得囉嗦嗎? 下面是整理過後的樣子:
problemManagement
│ ├── index.vue
│ ├── retrieve.vue
qualityCheckAppeal
└── index.vue
複製程式碼
3. 路由
我們系統裡的路由都是一級路由。舉個例子:
userManagement
├── add.vue
└── update.vue
複製程式碼
使用者管理下有增改兩個功能,不使用彈框去做的前提下,假如說 add
和 update
對應兩個路由是 /addUser
,/updateUser
。我們系統位址列是這樣顯示的:
// 增加使用者
localhost:3030/addUser
// 修改使用者
localhost:3030/updateUser?id=1
複製程式碼
雖然位址列路由短看起來會讓人舒服,但是模組多的話,就不容易區分,其實應該這樣做:
// 增加使用者
localhost:3030/user/add
// 修改使用者
localhost:3030/user/update?id=1
...
// 總結
localhost:3030/module/function?queryString
複製程式碼
當然也可以使用最近流行的 RESTful API 設定規範,專門用於 Web 資料結構的設定。阮一峰老師有一篇非常不錯的文章,推薦給大家,我就不再贅述辣。傳送門->
4. Vue 元件
關於 Vue 元件開發規範可以參考官方的風格指南。下面是我們專案的一些問題清單和改正意見,我列舉一下作為對照:
- 不要在
App.vue
中直接修改第三方樣式(比如:ElementUI
)。請使用外部檔案匯入:
App.vue
檔案:
<!-- incorrect -->
...
<style>
.el-input__icon {
cursor: pointer
}
</style>
<!-- correct -->
...
<style>
@import 'element-style-overwrite';
...
</style>
複製程式碼
_element-style-overwrite.scss
外部樣式檔案:
.el-input__icon {
cursor: pointer
}
複製程式碼
- 給每個元件起個名字是個好習慣。例如
Dialog
元件:
// incorrect
export default {
...
}
// correct
export default {
name: 'MyDialog', // 以大駝峰命名
...
}
複製程式碼
- 給元件樣式設定作用域
scoped
如果你在某個子元件中修改了全域性樣式,本來只想在該元件中使用,沒想到造成了全域性汙染。等進行程式碼 review 的時候是很難排查的。
例如,使用者管理(UserManagement.vue
)元件:
<style scoped>
...
</style>
複製程式碼
- 元件名要麼單詞大寫開頭 (PascalCase),要麼橫線連線(kebab-case):
// incorrect
components/
└── mycomponent.vue
components/
└── myComponent.vue
// correct
components/
└── MyComponent.vue
// 或者
components/
└── my-component.vue
複製程式碼
- .vue 單檔案中的
<template>
、<script>
、<style>
標籤的順序問題
有的人喜歡這樣寫:
<style>...</style>
<template>...</template>
<script>...</script>
複製程式碼
也有人喜歡這樣寫:
<script>...</script>
<style>...</style>
<template>...</template>
複製程式碼
如果你想寫,那好,不阻攔,拜託你統一下行不?別這個元件這個順序,那個元件那個順序。累不累? 這裡我強力推薦大家按照官方的寫法,即下面的順序來寫:
<template>...</template>
<script>...</script>
<style scoped>...</style>
複製程式碼
- 元件中的字型圖示(icon)不要用 png 圖片
不知道你們專案裡有沒有很多 icon 圖示。反正我們專案不少且都是 png 圖片。靜態資料夾裡好多小圖示。本來左側選單也都是 png 圖示的,被我看著不爽重構了一下。把所有的 png 圖示換成了 fontIcon 字型。
字型圖示的優勢:
- 減少 http 請求和專案體積
- 樣式容易控制
- 使用者體驗好
如何製作 fontIcon 字型圖示呢?其實很簡單:
-
1、可以先去阿里相簿找自己喜歡的或者讓你自己家的UI小姐姐做。
-
2、下載 svg 格式的,如果是UI做的,記得讓她轉換下。
-
3、去 icomoon 字型圖示生成網站匯入剛才所有的 svg 圖示,設定字型名稱匯出即可。
-
4、再在檔案中引用,大功告成。
-
使用兩個空格(space)進行縮排
這個放在全域性規範會比較好一些。為什麼是兩個空格? 大神們都是這樣做的!而且更重要的是,使用兩個空格開發專案,傳到 github 或者 gitlab 上排版會很好看。什麼?不會設定?百度啊!你用的什麼編輯器就查這個編輯器怎麼設定的。
一般是統一把全域性規範設定放到一個叫 .editorconfig 的資料夾裡,有的編輯器支援這個檔案,比如:webstorm
。有的則不支援,對於不支援的編輯器,可以下載安裝 editorConfig
外掛,如:atom
、sublime
、vscode
等。
-
程式碼中不用的註釋都刪掉
-
除錯結束,把不用的
console.log(...)
及時刪掉,它會影響效能 -
data
中的屬性命名和初始化問題
// incorrect
export default {
data () {
return {
text: 'wwwwwwww', // 這是啥?
editBoxId: null, // 很明顯Id是String,這裡他初始化一個 null
flag: '', // 這個表示的啥?看意思應該是個 Boolean 型別,為啥弄個 String ?
pSize: 10, // pSize 是啥?
cPage: 1, // cPage 是啥?
popCsr:true, // popCsr 是啥,恐怕現在連那個開發者自己都不知道了吧
callcenterAuthority: false, // 這麼長你告訴是一個 Boolean 型別的
}
}
}
// correct
export default {
data () {
return {
text: '', // 'wwwwwwww' 沒鳥用刪掉
editBoxId: -1, // 它應該是個 Number 型別
flag: false, // 它應該是個 Boolean 型別啊
pageSize: 10, // pSize -> pageSize 多好
currentPage: 1, // 完整寫法更易懂,不是嗎?
isPopcsr: true, // Boolean 型別的總是前面加個 is
isAuthority: false, // 是否授權。
}
}
}
複製程式碼
其實還有好多問題,我就不一一列舉了。諸如此類的問題,希望各位看客們都能吸取精華,去其糟粕。
Props
中的屬性宣告要明確型別
// incorrect
export default {
props: ['node', 'size']
}
// correct
export default {
props: {
node: Object, // 物件
size: [String, Number], // 兩種型別都可以
}
}
複製程式碼
- Vue 生命週期函式按順序放在
methods
之前
為什麼說這個呢? 我們專案中有的元件就 methods
中的程式碼就上千行。如果生命週期函式放在 methods
之後,拉來拉去非常不方便:
// incorrect
export default {
...
created () {},
methods: {
// 省略 1000 行程式碼
// ...
},
mounted () {},
beforeDestroy () {},
destroy () {},
}
// correct
export default {
...
created () {},
mounted () {},
beforeDestroy () {},
destroy () {},
methods: {
// 省略 1000 行程式碼
// ...
}
}
複製程式碼
- Vue 元件中的
this
賦值要統一
程式碼中,有時候我們需要把 this
賦給一個變數,你要麼統一賦值給變數 vm
,要麼統一賦值給變數 self
。別一個元件裡,變來變去。
// incorrect
export default {
...
methods: {
one () {
let vm = this
},
two () {
let self = this
}
}
}
// incorrect
export default {
...
methods: {
one () {
let vm = this
// 或者
let self = this
},
two () {
let vm = this
// 或者
let self = this
}
}
}
複製程式碼
- Vue 元件中 Html 如果過長,請換行
<!-- incorrect -->
<el-input v-model="ruleForm.maskInput" size="small" class="nodeIpt" :icon="ruleForm.maskInput ? 'circle-close':''" @click="ruleForm.maskInput = ''" @keyup.enter.native="nodesure($event,'ruleForm')"></el-input>
<!-- correct -->
<el-input
v-model="ruleForm.maskInput"
size="small"
class="nodeIpt"
:icon="ruleForm.maskInput ? 'circle-close':''"
@click="ruleForm.maskInput = ''"
@keyup.enter.native="nodesure($event,'ruleForm')">
</el-input>
複製程式碼
- Vue 中監聽的事件記得垃圾回收
舉個例子,如果我們在 Vue 元件的 created
宣告週期鉤子中監聽了一個點選事件,那麼,當元件銷燬(beforeDestroy)之前記得把這個事件釋放,看程式碼:
export default {
...
created () {
document.addEventListener('click', this.handleClick)
},
beforeDestroy () {
document.removeEventListener('click', this.handleClick)
}
}
複製程式碼
- Vue 元件中不要直接操作非同步請求(axios)
把所有的非同步請求方法封裝成一個獨立 js 檔案,或者放到 Vuex 中,千萬不要耦合到 Vue 元件中。因為程式碼量太多,會加重元件的後期維護,各司其職不好嗎?
不好的範例:
// User.vue
export default {
...
mounted () {
this.getUsers()
},
methods: {
getUsers () {
this.axios(url, data, (response) => {
// Do something
}).catch(err => {
console.error(err)
})
}
}
}
複製程式碼
如果專案比較小還好,我沒意見,如果專案較複雜,千萬別這麼幹。下面是推薦的做法:
// server.js
// 專門處理資料請求的檔案,也就是我沒常說的MVC中的 M 層
import axios from 'axios'
export default {
/**
* 獲取使用者列表
*/
getUsers (url, data) {
return axios.get(url, data)
}
}
// User.vue
import api from '@/api/server.js'
export default {
...
data () {
return {
users: null
}
},
mounted () {
api.getUsers((response) => {
this.users = response.data.data
}).catch(err => {
console.log(err)
})
}
}
複製程式碼
5. JavaScript
下面所有的錯誤程式碼示例都是從我們的專案中發現的,撿主要的列出來一些。希望犯同樣錯誤的你能及時改正哦~
- 變數命名
要語義化命名
// incorrect
var a = document.getElementById(this.lastid) // 這裡的 a
var aa = true // 這是啥你們知道嗎?
// corrent
let orderId = this.order.id
let currentTime = Date.now()
複製程式碼
- 多個單詞要駝峰命名
// incorrent
vm.timedefault = timedvalue
vm.currentsessionid = id
// corrent
vm.timeDefault = timedValue
vm.currentSessionId = id
複製程式碼
- 變數要加註釋
- 不要重複使用 var 宣告變數
// incorrect
var name = 'test';
var age = 12;
var hobby = 'sport';
// correct
var name = 'test',
age = 12,
hobby = 'sport';
複製程式碼
=
或==
之間要保留一個空格
錯誤的範例:
// 變數
var name='test'
var arr=[]
var obj={
id:1
}
// if 判斷
if(this.id==currentId){
// Do something
}
// for 迴圈
for(let i=0;i<arr.length;i++){
// Do something
}
複製程式碼
上面三種情況是最常見的,其他雷同。下面是正確的範例:
// 變數
var name = 'test'
var arr = []
var obj = {
id: 1
}
// if 判斷
if(this.id == currentId) {
// Do something
}
// for 迴圈
for(let i = 0; i < arr.length; i++) {
// Do something
}
複製程式碼
- 右括號
)
遇到 左大括號{
時要空一格
下面是錯誤的範例:
// if
if(a === b){
// Do something
}
// for
for(let i = 0; i < arr.length; i++){...}
// 函式
var T = function(params){
...
}
複製程式碼
常見的幾種情況,其他情況不再列舉。下面是正確的範例:
// if
if (a === b) {
// Do something
}
// for
for (let i = 0; i < arr.length; i++) {...}
// 函式
var T = function(params) {
...
}
複製程式碼
- 非空判斷問題
在我們專案裡,有人這樣寫:
// 假如 Vue 元件中有一個叫 userId 的 data 屬性
if (userId != '' || userId != 0 || userId != false || userId != null || userId != undefined) {
// ...
}
複製程式碼
當遇到上面幾種情況的時候,下面程式碼實現的效果是一樣的:
if (!userId) {
// ...
}
複製程式碼
- 物件宣告問題
不要用下面的方式之一去宣告一個物件:
// incorrect
var arr = new Array() // 陣列
var arr = '' // 雖然 js 是弱型別,也不能這樣宣告
var obj = new object() // 物件
var obj = ''
複製程式碼
下面是推薦做法,也是大眾做法:
// 宣告陣列
let arr = []
// 宣告物件
let obj = {}
// or
let obj = null
複製程式碼
- 異常處理問題
我們在處理非同步請求的時候,一定要對 response 中的資料進行異常處理,不然控制檯回報 response.data is not undefined
,我們專案我看了下,有些地方沒做處理,結果在做測試的時候,瀏覽器控制檯一頓報錯。那叫一個難看啊!
// incorrect
this.axios(url, data, (response) => {
let result = response.data.data
})
// correct
this.axios(url, data, (response) => {
if (response.data && response.data.code === 1) {
let result = response.data.data
}
}).catch(err => {
console.error(err)
})
複製程式碼
- 如果這個取值過長且多次用到,請賦給一個變數
export default {
...
methods: {
handleClick (evt) {
// incorrect
evt.target.parentNode.innerHTML = 'test'
evt.target.style.width = '100px'
evt.target.style.height = '200px'
// correct
let target = evt.target
target.parentNode.innerHTML = 'test'
target.style.width = '100px'
target.style.height = '200px'
}
}
}
複製程式碼
6. HTML
- 正確的使用標籤
專案中我見有人寫個按鈕居然用 span
標籤,或者一個 div
。
下面是錯誤的範例:
// 用 div 當按鈕
<div class="btn">搜尋</div>
// 在 span 裡 巢狀 el-input 元件
// 這樣做的同學,肯定不知道 el-input 編譯後的程式碼是啥樣的!
<span>
<el-input></el-input>
</span>
// 用 label 當標題
// label 標籤是配合表單使用的
<label>標題</label>
// 加粗字型沒有用原生標籤
<span class="bold">我是加粗字型</span>
複製程式碼
下面是改正後的範例:
// 用 H5 的 button
<button class="btn">搜尋</button>
// 如果要包含 el-input 元件請使用塊級元素,並加上合適的 class
<div class="el-input__wrapper">
<el-input></el-input>
</div>
// h1-h6 才是標題的正確開啟方式
<h2>標題</h2>
// 加粗字型請使用原生標籤
// 然後使用 class 控制字型樣式
<strong class="bold">我是加粗字型</strong>
複製程式碼
- 所有的按鈕,超連結,滑鼠的
:hover
狀態都應該是手形。
a, button {
cursor: pointer
}
複製程式碼
- id 和 class 或者其他的屬性,命名要語義化
不要命個名只有你自己知道。這樣會帶來後期維護困難。
<!-- incorrect -->
<div class="dfdf">
<el-form class="loginForm">...</el-form>
</div>
<!-- correct -->
<div class="login-form__wrapper">
<el-form class="loginForm">...</el-form>
</div>
複製程式碼
- 把程式碼縮排改成 2 個空格
- Html 中的屬性之間保留一個空格距離
<!-- incorrect -->
<el-input v-model="form.loginUser" size="small" placeholder="請輸入使用者名稱"></el-input>
<!-- 不覺的上面的程式碼很醜嗎,我知道你或許不會這樣做 -->
<!-- 但還真有人這樣做 -->
<!-- 下面是改進後的程式碼 -->
<el-input v-model="form.loginUser" size="small" placeholder="請輸入使用者名稱"></el-input>
複製程式碼
- 每個程式碼快儘量加上註釋
程式碼量少尚且不說,如果一個 .vue 檔案很長的話,找起來就很痛苦了。你還別說,我們專案裡就是這樣沒註釋。
<!-- 正確的示範 -->
<template>
<div class="user-managerment__wrapper">
<!-- Header -->
<div class="header">...</div>
<!-- User table -->
<div class="user-table__wrapper">
<el-table>...</el-table>
</div>
<!-- Add user dialog -->
<div class="add-user__dialog">
<el-dialog title="新增使用者">...</el-dialog>
</div>
</div>
</template>
複製程式碼
7. CSS
{
和選擇器保持一個空格距離
.selector {
...
}
複製程式碼
- 給每個樣式模組加上註釋有助於區分
// Global style
html, body, a, div {
margin: 0
}
// Login style
.login button {
...
}
// User manager style
.user-manager__wrapper {
...
}
複製程式碼
- 每個獨立樣式間保留一行距離
見上面的示例
- 選擇器不要巢狀太多層級
巢狀太多層級會影響效能,儘量保證在三層以下:
// incorrect
.user-management .user-box .user-form .el-form-item .remark {
color: #42b983
}
// correct
.user-management .user-form .remark {
color: #42b983
}
複製程式碼
8. Git 程式碼提交
- 提交前先 pull 程式碼
寫程式碼前記得先 pull 下別人的程式碼,這是個好習慣。別等到自己寫完 push 後才發現程式碼有衝突。
# pull
git pull
# modified
git add someFiles
git commit -m "..."
git push
複製程式碼
- 寫好提交註釋
大家可以看我 沸點。同事寫的註釋。希望有問題的同學可以及時改正哦。另外,關於 Git 如何正確的寫好註釋,這裡有幾篇文章講的很好,大家可以看看:
下面舉個例子,比如我這次在使用者管理模組中修改了兩個 bug。如何以清單的方式提交呢? 看程式碼:
# add file
git add src/components/userManager/index.vue
# commit
git commit -m 'fix: 使用者管理模組bug修改。
修改內容:
- 修改了列表分頁的bug
- 修改了當使用者點選編輯按鈕彈框無法顯示的bug
'
# push code
git push
複製程式碼
你千萬別用下面的方式之一去提交你的程式碼說明:
# 說一些毫無意義的內容
git commit -m "fix: ok!"
# or 不加 fix、feat、refactor、doc、style等字首
# 為什麼要加這些字首呢?問得好!
# 是方便日後檢索,當我們以這些字首去搜尋修改日誌的時候
# 是很容易的哦,微笑。
git commit -m "修改使用者模組bug"
複製程式碼
總結
最後,給大家找了幾個大廠的團隊規範文件,希望你看完能夠受益多多:
以上就是我在專案當中發現的一些問題,記錄下來,暫時就記錄這麼多吧。希望正好看d到這篇文章的你如果也正好有以上的不良問題,請加油改正哦。當你的程式碼質量又提升一個檔次的時候,我相信,你離前端大神之門又邁進了一步!
囉嗦了這麼多,希望看到的同學或多或少有點收穫吧。不對的地方還請留言指正,不勝感激。俗話說,三人行則必有我師,希望更多志同道合的小夥伴能聚在一起交流技術!下面是我在維護的一個Q群,也可以加我 Q1769617251 。備註 vue 即可。