編程規(guī)約
規(guī)范的目的是為了編寫高質(zhì)量的代碼， 讓你的團(tuán)隊(duì)成員每天得心情都是愉悅的播掷， 大家在一起是快
樂的
一季二、命名規(guī)范
:snake: kebab-case 指短橫線命名法，而 camel-case 指駝峰命名法
1.1 項(xiàng)目命名
全部采用小寫方式舀寓，用-分割
-
mall-management-system:white_check_mark: -
mall_management_system、mallMangementSystem:negative_squared_cross_mark:
1.2 目錄命名
全部采用小寫肌蜻，以中劃線分割互墓，有復(fù)數(shù)結(jié)構(gòu)時(shí)，要采用復(fù)數(shù)命名法 蒋搜，縮寫是不用復(fù)數(shù)的
-
scripts/styles/components/images/demo-styles/img/doc:white_check_mark: -
script/demo_scripts/demoStyles/imgs/docs:negative_squared_cross_mark:
Vue 項(xiàng)目中目錄使用 kebab-case 命名
-
head-search / page-loading:white_check_mark: -
HeadSearch / PageLoading:negative_squared_cross_mark:
1.3 JS篡撵、CSS、SCSS豆挽、HTML育谬、PNG文件命名
全部用 kebab-case 命名
-
render-dom.js / signup.css /index.html / company-logo.png:white_check_mark: -
renderDOM.js / UserMangement.html:negative_squared_cross_mark:
1.4 代碼命名嚴(yán)謹(jǐn)性
代碼命名嚴(yán)禁使用拼音與英文混合的方式，更不允許使用中文的方式帮哈。
-
hennan/luoyang/rmb等國際通用名稱膛檀，可視為英文 :white_check_mark: -
DaZhePromotion/getPingfenByName:negative_squared_cross_mark:
杜絕不規(guī)范的縮寫，避免望文生意但汞。
-
AbstractClass -> AbsClass / condition -> condi:negative_squared_cross_mark:
二宿刮、HTML規(guī)范
適用 Vue template
2.1 HTML類型
使用 HTML5 的文檔類型聲明 ，文檔中需要聲明如下元素
- 規(guī)定字符編碼
- IE 兼容模式
- 規(guī)定字符編碼
- doctype 大寫
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Document</title>
</head>
<body>
</body>
</html>
2.2 縮進(jìn)
縮進(jìn)使用 2 個(gè)空格(一個(gè)tab)私蕾，嵌套的節(jié)點(diǎn)應(yīng)該縮進(jìn)
2.3 分塊注釋
在每一個(gè)塊狀元素僵缺、列表元素、表格元素后踩叭，加上一對(duì) HTML 注釋
2.4 語義化標(biāo)簽
使用 HTML5 語義化標(biāo)簽磕潮，避免每一個(gè)節(jié)點(diǎn)都是 <div> 或者 <p>
2.5 引號(hào)
使用雙引號(hào)""而不是單引號(hào)''
-
<div class="list"></div>:white_check_mark: -
<div class='list'></div>:negative_squared_cross_mark:
三翠胰、CSS規(guī)范
- 類名使用 kebab-case
- id 采用 camel-case
- 預(yù)處理語言中的變量、函數(shù)自脯、混合之景、placeholder采用 camel-case
3.1 命名
id 或者 class 名稱 反映元素目的與用途，或者其他通用的名稱
不推薦:negative_squared_cross_mark:
.mr100 {
margin-top : 100px;
}
.red {
color : red;
}
推薦:white_check_mark:
.roof {
margin-top : 100px;
}
.important {
color : red;
}
3.2 選擇器
css 選擇器避免使用標(biāo)簽名
從結(jié)構(gòu)膏潮、表現(xiàn)锻狗、行為分離情況看，應(yīng)該避免在css中出現(xiàn) HTML標(biāo)簽 焕参，并且在 css 選擇器中出現(xiàn)標(biāo)簽名會(huì)存在潛在的問題
使用直接子選擇器
.content>.title:white_check_mark:.content .title:negative_squared_cross_mark:
使用縮寫屬性
margin : 100px 100px 0 0:white_check_mark:margin-top:100px;margin-right:100px:negative_squared_cross_mark:
省略 0 后面的單位
-
margin-top : 0:white_check_mark: -
margin-top : 0px:negative_squared_cross_mark:
避免使用標(biāo)簽選擇器污染全局樣式
-
.header { ... }:white_check_mark: -
header { ... }:negative_squared_cross_mark:
四轻纪、預(yù)處理語言規(guī)范
用 scss 舉例
4.1 代碼組織
公共文件存放
應(yīng)該將公共文件存放在 style/scss/common 文件夾中。
例如 style/scss/common/color.scss
組織樣式文件
應(yīng)該按照以下順序組織
- @import
- 變量命名
- 樣式聲明
@import '~style/mixins/size.scss'
$defaultTextColor : #333;
.page {
...
}
4.2 避免嵌套層級(jí)過多
嵌套深度限制在3級(jí)叠纷，超過或者為4級(jí)的嵌套刻帚。應(yīng)該重新評(píng)估。這可以避免大量的嵌套規(guī)則
推薦 :white_check_mark:
.main-title {
.name {
...
}
}
不推薦 :white_check_mark:
.main {
.title {
.name {
...
}
}
}
五涩嚣、JavaScript規(guī)范
5.1 命名
變量命名
采用小寫 camel-case 崇众，代碼中的命名不能以下劃線，也不能以下劃線或者$符號(hào)結(jié)束
-
_name/name_/name$:negative_squared_cross_mark:
方法名航厚、參數(shù)名顷歌、成員變量
統(tǒng)一使用 小寫 camel-case
-
localValue/getHttpMessage()/inputUserId:white_check_mark:
其中，method 方法必須是 動(dòng)詞 + 名詞 形式
-
saveShopCarData / openShopCarInfoDialog:white_check_mark: -
save / open / show / go:negative_squared_cross_mark:
特別地阶淘，增刪改查必須使用如下單詞
add / update / delete / detail / get
另外衙吩，常見的動(dòng)詞如下 :
get 獲取/set 設(shè)置,
add 增加/remove 刪除,
create 創(chuàng)建/destory 銷毀,
start 啟動(dòng)/stop 停止,
open 打開/close 關(guān)閉,
read 讀取/write 寫入,
load 載入/save 保存,
begin 開始/end 結(jié)束,
backup 備份/restore 恢復(fù),
import 導(dǎo)入/export 導(dǎo)出,
split 分割/merge 合并
get 獲取/set 設(shè)置,
add 增加/remove 刪除,
create 創(chuàng)建/destory 銷毀,
start 啟動(dòng)/stop 停止,
open 打開/close 關(guān)閉,
read 讀取/write 寫入,
load 載入/save 保存,
begin 開始/end 結(jié)束,
backup 備份/restore 恢復(fù),
import 導(dǎo)入/export 導(dǎo)出,
split 分割/merge 合并
常量命名
全部使用大寫互妓，單詞用下劃線隔開溪窒。力求語義完整清楚，不要嫌名字長
-
LOAD_ERROR_TYPE:white_check_mark: -
LOAD_TYPE:negative_squared_cross_mark:
5.2 代碼格式
縮進(jìn)
使用兩個(gè)空格進(jìn)行縮進(jìn)
空行
不同邏輯冯勉、不同語義澈蚌、不同業(yè)務(wù)的代碼之間插入一個(gè)空行分隔來提高可讀性。
引號(hào)
統(tǒng)一使用''創(chuàng)建字符串
5.3 對(duì)象
使用字面量
使用字面量格式創(chuàng)建對(duì)象
let user = {}
5.4 優(yōu)先使用es6
必須優(yōu)先使用 es6 新增的語法糖與函數(shù)灼狰。這將簡化你的程序宛瞄。
5.5 括號(hào)
下面關(guān)鍵字后必須跟括號(hào)，哪怕代碼內(nèi)容只有一行交胚。
if/else/for/while/do/switch/try/catch/finally/with
5.6 undefined判斷
永遠(yuǎn)不要使用 undefined 直接進(jìn)行變量判斷份汗；而是使用 typeof結(jié)合字符串undefined判斷
-
if(typeof person === 'undefined') {}:white_check_mark: -
if(person === undefined):negative_squared_cross_mark:
5.7 條件判斷和循環(huán)最多三層
- 能用三目運(yùn)算符則使用三目運(yùn)算符
- 如果超過三層請(qǐng)抽象為函數(shù)
不推薦 :negative_squared_cross_mark:
if(item.status == 2 && item.statusName === '正在直播' && localStorage.get('SHOW_DIDALOG')) {
...
}
推薦 :white_check_mark:
function checkShowDialog(item) {
return item.status == 2 && item.statusName === '正在直播' && localStorage.get('SHOW_DIDALOG')
}
if(checkShowDialog(item)) {
...
}
5.8 this引用命名
對(duì)于上下文的 this 引用只能用 self 進(jìn)行命名
5.9 慎用console.log
因?yàn)?console.log 大量使用會(huì)有性能問題，所以在非webpack項(xiàng)目中謹(jǐn)慎使用 log 功能
六蝴簇、命名參考
6.1 變量命名
(1). 表示可預(yù)見杯活、進(jìn)行中的狀態(tài)
可見性例如 v-show，進(jìn)行中說明某種狀態(tài)持續(xù)進(jìn)行中
推薦命名方式 js +動(dòng)詞 (現(xiàn)在進(jìn)行時(shí))
{
isShow: '是否顯示',
isVisible: '是否可見',
isLoading: '是否處于加載中',
isConnecting: '是否處于連接中',
isValidating: '正在驗(yàn)證中',
isRunning: '正在運(yùn)行中',
isListening: '正在監(jiān)聽中'
}
(2). 屬性狀態(tài)類
用于描述視圖的功能屬性熬词，寫法和用法比較固定
{
disabled: '是否禁用',
editable: '是否可編輯',
clearable: '是否可清除',
readonly: '只讀',
expandable: '是否可展開',
checked: '是否選中',
enumberable: '是否可枚舉',
iterable: '是否可迭代',
clickable: '是否可點(diǎn)擊',
draggable: '是否可拖拽'
}
(3). 配置類旁钧、選項(xiàng)類
主要指組件功能的開啟與關(guān)閉吸重、功能屬性的配置
- withXx 表示組件在基本功能形態(tài)的其他功能，例如高級(jí)功能
- enableXx 表示組件某些功能的開啟
- allowXx 表示功能屬性的配置
- noXx 表示建議功能歪今，用于配置不建議開啟的功能
{
withTab: '是否帶選項(xiàng)卡',
withoutTab: '不帶選項(xiàng)卡',
enableFilter: '開啟過濾',
allownCustomScale: '允許自定義縮放',
shouldClear: '是否清除',
canSelectItem: '是否能選中元素',
noColon: '不顯示label后面的冒號(hào)',
checkjs: '檢查js',
emitBOM: 'Emit a UTF-8 Byte Order Mark (BOM) in the beginning of output files.'
}
除了上述這些帶有特定的前置介詞嚎幸、動(dòng)詞以外還有一些語義上有疑問性質(zhì)的組合也作為Boolean命名的參考
{
virtualScroll: '是否啟用虛擬滾動(dòng)模式',
unlinkPanels: '在范圍選擇器里取消兩個(gè)日期面板之間的聯(lián)動(dòng)',
validateEvent: '輸入時(shí)是否觸發(fā)表單的校驗(yàn)'
}
(4). 數(shù)組命名
數(shù)組命名推薦復(fù)數(shù)命名，還有就是名詞和具有列表意思的單詞組合 見的詞匯有 options, list, maps, nodes, entities, collection 等寄猩。
{
users: '用戶列表',
userList: '用戶列表',
tabOptions: '選項(xiàng)卡選項(xiàng)',
stateMaps: '狀態(tài)映射表',
selectedNodes: '選中的節(jié)點(diǎn)',
btnGroup: '按鈕組',
userEntities: '用戶實(shí)體'
}
(5). 選項(xiàng)元素嫉晶、下拉元素命名
主要針對(duì)的是在下拉選擇框、選項(xiàng)卡元素田篇、Radio车遂、Checkbox等數(shù)據(jù)源每個(gè)選項(xiàng)數(shù)據(jù)的命名。常見的詞匯有：title, name, key, label, field, value, id, children, index, nodes 等斯辰。
// 最常見組合
{
title: '標(biāo)題',
value: 'ID值'
}
// 組合二
{
label: '標(biāo)簽名',
value: 'ID值'
}
// 組合三
{
name: '元素名',
id: 'ID值'
}
// 組合四
{
field: '字段',
value: '標(biāo)識(shí)',
index: '索引'
}
(6). 激活項(xiàng)命名
{
activeTab: '當(dāng)前選中選項(xiàng)卡',
currentPage: '當(dāng)前頁',
selectedData: '當(dāng)前選項(xiàng)中數(shù)據(jù)',
}
(7). 臨時(shí)數(shù)據(jù)舶担、比對(duì)數(shù)據(jù)命名
{
swapData: '臨時(shí)交換數(shù)據(jù)',
tempData: '臨時(shí)數(shù)據(jù)',
dataSnapshot: '數(shù)據(jù)快照'
}
6.2 函數(shù)命名
函數(shù)命名的方式常常是和業(yè)務(wù)邏輯耦合在一起的，但是在命名規(guī)則上也有一些常見的模式可以遵循彬呻。
(1). 事件處理
事件處理函數(shù)是前端平時(shí)用到最多的衣陶，包括瀏覽器原生事件、異步事件和組件自定義事件闸氮。例如最為常見的
- onXx
- onXxClick
- handleXx
- handleXxChange
這里如何在二者之間選擇剪况，可以從二方面來歸類。
- 原生事件采用 onXx
- 自定義事件使用 handleXx蒲跨。
- 事件主動(dòng)監(jiān)聽采用 onXx
- 被動(dòng)處理使用 handleXx译断。
從實(shí)踐及三大主流框架的文檔關(guān)于事件部分的內(nèi)容來看，推薦使用 handleAction 這種方式或悲，而在表單提交的時(shí)候通常采用onSubmit函數(shù)孙咪。
但還有一些約定俗稱的例子
{
onSubmit: '提交表單',
handleSizeChange: '處理分頁頁數(shù)改變',
handlePageChange: '處理分頁每頁大小改變',
onKeydown: '按下鍵'
}
(2).異步處理
- fetch/get 獲取數(shù)據(jù)
- update / delete / remove /create 操作數(shù)據(jù)
6.3 數(shù)據(jù)加工
這類場景在處理列表的時(shí)候經(jīng)常會(huì)碰到，比如排序巡语、過濾翎蹈、添加額外的字段、根據(jù)ID和索引獲取特定數(shù)據(jù)等
(1). 根據(jù)特定屬性獲取對(duì)象
這里可以參考DOM方法的命名男公，比如：getElememtById()荤堪、getElementsByTagName()、getElementsByClassName() 和 getElementsByName()
{
getItemById: '根據(jù)ID獲取數(shù)據(jù)元素',
getItemsBySelected: '根據(jù)傳入的已選列表ID來獲取列表全部數(shù)據(jù)',
queryUserByUid: '根據(jù)UID查詢用戶'
}
(2). 格式化數(shù)據(jù)
這里的格式化操作包括排序枢赔、調(diào)整數(shù)據(jù)結(jié)構(gòu)澄阳、過濾數(shù)據(jù)、添加屬性踏拜。命名通常使用 formatXx, convertXx, inverseXx, toggleXx, parseXx, flatXx, 也可以結(jié)合數(shù)組的一些操作方法來命名碎赢，比如 sliceXx, substrXx, spliceXx, sortXx, joinXx 等來命名。
{
formatDate: '格式化日期',
convertCurrency: '轉(zhuǎn)換貨幣單位',
inverseList: '反轉(zhuǎn)數(shù)據(jù)列表',
toggleAllSelected: '切換所有已選擇數(shù)據(jù)狀態(tài)',
parseXml: '解析XML數(shù)據(jù)',
flatSelect: '展開選擇數(shù)據(jù)',
sortByDesc: '按降序排序'
}
