前端代碼規範
- 前言
- 一、唯一定律
- 二、前段代碼規範
- (一)命名規範
- (二)HTML 規範
- 2.1 、HTML 類型
- 2.2 、縮進
- 2.3、分塊註釋
- 2.4、語義化標籤
- 2.5、引號
- 2.6、閉合標籤
- 2.7、引入CSS和JavaScript
- 2.8、屬性順序
- 2.9、布爾型屬性
- 2.10、減少標籤的數量
- 2.11、減少 JavaScript 生成的標籤
- 2.12、提示
- (三) CSS 規範
- 3.1、命名
- 3.2、選擇器
- 3.3、儘量使用縮寫屬性
- 3.4、選擇器及屬性獨佔一行
- 3.5、省略0後面的單位
- 3.6、避免使用ID選擇器
- 3.7、分號結尾
- 3.8、省略 0.X前面的0
- 3.9、十六進制值全部小寫
- 3.10、屬性聲明順序
- 3.11、重置樣式
- (四)JavaScript規範
前言
最近自己想開發一個網站,所以編寫了前端和java的響應的代碼規範,其實都是整合別人的覺得合適的規範。
本規範的目的是爲了編寫靈活、穩定、高質量的代碼,讓每個團隊成員每天得心情都是愉悅的,一起開心的coding
一、唯一定律
無論有多少人共同參與同一項目,一定要確保每一行代碼都像是唯一個人編寫的。
二、前段代碼規範
(一)命名規範
1.1、項目命名
全部採用小寫方式, 以中劃線分隔。
正例:cust-relation-system
反例:cust_relation_system
/ custRelationSystem
1.2 、目錄命名
全部採用小寫方式, 以中劃線分隔,有複數結構時,要採用複數命名法, 縮寫不用複數
正例: scripts / styles / components / images / utils / layouts / demo-styles / demo-scripts / img / doc
反例: script / style / demo_scripts / demoStyles / imgs / docs
1.3、文件存放位置
文件夾名稱 | 文件夾含義 |
---|---|
image | 存放圖片文件 |
media | 存放多媒體文件 |
library | 第三方依賴包 |
js | 存放JavaScript腳本 |
css | 存放CSS文件 |
1.4、JS、CSS、HTML、PNG 等文件命名
全部採用小寫方式, 以中劃線分隔
正例: render-dom.js / signup.css / index.html / company-logo.png
反例: renderDom.js / UserManagement.html
1.4、命名嚴謹性
代碼中的命名嚴禁使用拼音與英文混合的方式,更不允許直接使用中文的方式。 說明:正確的英文拼寫和語法可以讓閱讀者易於理解,避免歧義。注意,即使純拼音命名方式也要避免採用
正例:shanghai / beijing / rmb 等國際通用的名稱,可視同英文。
反例:DaZhePromotion [打折] / getPingfenByName() [評分] / int 某變量 = 3
杜絕完全不規範的縮寫,避免望文不知義:
反例:condition“縮寫”命名成 condi,此類隨意縮寫嚴重降低了代碼的可閱讀性。
1.5、代碼註釋
代碼內文檔在軟件設計中起着至關重要的作用。 註釋對於幫助開發人員理解系統和有效地工作是必不可少的,但是註釋的作用遠遠不止於此。文檔在抽象中也扮演着重要的角色;沒有註釋,就無法隱藏複雜性。最後,編寫註釋的過程如果處理正確,實際上將改進系統的設計。相反,如果沒有良好的文檔記錄,好的軟件設計就會失去很多價值。
我們要保持良好的註釋習慣,保證程序的可閱讀性,好的程序應首先易於閱讀,其次纔是效率高低的問題。
1.5.1、HTML單行註釋
一般用於簡單的描述,如某些狀態描述、屬性描述等
註釋內容前後各一個空格字符,註釋位於要註釋代碼的上面,單獨佔一行
推薦:
<!-- Comment Text -->
<div>...</div>
不推薦:
<div>...</div><!-- Comment Text -->
<div><!-- Comment Text -->
...
</div>
1.5.2、HTML模塊註釋
一般用於描述模塊的名稱以及模塊開始與結束的位置
註釋內容前後各一個空格字符,表示模塊開始,
表示模塊結束,模塊與模塊之間相隔一行
推薦寫法:
<!-- S Comment Text A -->
<div class="mod_a">
...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->
<div class="mod_b">
...
</div>
<!-- E Comment Text B -->
不推薦寫法:
<!-- S Comment Text A -->
<div class="mod_a">
...
</div>
<!-- E Comment Text A -->
<!-- S Comment Text B -->
<div class="mod_b">
...
</div>
<!-- E Comment Text B -->
1.5.3、HTML嵌套模塊註釋
當模塊註釋內再出現模塊註釋的時候,爲了突出主要模塊,嵌套模塊不再使用
<!-- S Comment Text -->
<!-- E Comment Text -->
而改用
<!-- /Comment Text -->
註釋寫在模塊結尾標籤底部,單獨一行。
<!-- S Comment Text A -->
<div class="mod_a">
<div class="mod_b">
...
</div>
<!-- /mod_b -->
<div class="mod_c">
...
</div>
<!-- /mod_c -->
</div>
<!-- E Comment Text A -->
1.5.4、CSS單行註釋
註釋內容第一個字符和最後一個字符都是一個空格字符,單獨佔一行,行與行之間相隔一行
推薦:
/* Comment Text */
.xiaoming {}
/* Comment Text */
.xiaoming {}
不推薦:
/*Comment Text*/
.xiaoming {
display: block;
}
.xiaoming {
display: block;/*Comment Text*/
}
1.5.5、模塊註釋
註釋內容第一個字符和最後一個字符都是一個空格字符,/*
與 模塊信息描述佔一行,多個橫線分隔符-
與*/
佔一行,行與行之間相隔兩行
推薦:
/* Module A
---------------------------------------------------------------- */
.mod_a {}
/* Module B
---------------------------------------------------------------- */
.mod_b {}
不推薦:
/* Module A ---------------------------------------------------- */
.mod_a {}
/* Module B ---------------------------------------------------- */
.mod_b {}
(二)HTML 規範
2.1 、HTML 類型
推薦使用 HTML5 的文檔類型申明:(建議使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的屬性,比如 application/xhtml+xml 在瀏覽器中的應用支持與優化空間都十分有限)。
-
語言屬性
-
規定字符編碼
-
IE 兼容模式
-
規定字符編碼
-
doctype 大寫
正例:
<!DOCTYPE html>
<html lang="zh">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta charset="UTF-8" />
<title>Page title</title>
</head>
<body>
<img src="images/company-logo.png" alt="Company" />
</body>
</html>
2.2 、縮進
前端縮進統一使用 2 個空格(可將一個html、css、js等文件設置一個tab爲兩個空格)
嵌套的節點應該縮進。
2.3、分塊註釋
在每一個塊狀元素,列表元素和表格元素後,加上一對 HTML 註釋。註釋格式
<!-- 英文 中文 start ->
<!-- 英文 中文 end -->
正例:
<body>
<!-- header 頭部 start -->
<header>
<div class="container">
<a href="#">
<!-- 圖片會把a標籤給撐開,所以不用設置a標籤的大小 -->
<img src="images/header.jpg" />
</a>
</div>
</header>
<!-- header 頭部 end -->
</body>
2.4、語義化標籤
HTML5 中新增很多語義化標籤,所以優先使用語義化標籤,避免一個頁面都是 div 或者 p 標籤
正例
<header></header>
<footer></footer>
反例
<div>
<p></p>
</div>
2.5、引號
使用雙引號(" ") 而不是單引號(’ ') 。
正例: “xiaoming”
反例: ‘xiaoming’
2.6、閉合標籤
- 不要在自閉合(self-closing)元素的尾部添加斜線( / ) –HTML5 規範中明確說明這是可選的
- 不要省略可選的結束標籤(closing tag)(例如, 或 )
2.7、引入CSS和JavaScript
根據 HTML5 規範,在引入 CSS 和 JavaScript 文件時一般不需要指定 type 屬性,因爲 text/css 和 text/javascript 分別是它們的默認值。
正例
<link rel="stylesheet" href="index.css">
<script src="index.js"></script>
反例
<link type="text/css" rel="stylesheet" href="index.css">
<script type="text/javascript" src="index.js"></script>
2.8、屬性順序
HTML 屬性應當按照以下給出的順序依次排列,確保代碼的易讀性。
(1)class
(2)id, name
(3)data-*
(4)src, for, type, href, value
(5)title, alt
(6)role, aria-*
例子
<a class="" id="" data-ref="" href=""></a>
<input class="" type="text">
<img src="" alt="">
2.9、布爾型屬性
1)布爾型屬性可以在聲明時不賦值。XHTML 規範要求爲其賦值,但是 HTML5 規範不需要。
2)元素的布爾型屬性如果有值,就是 true,如果沒有值,就是 false。
3)如果屬性存在,其值必須是空字符串或 […] 屬性的規範名稱,並且不要在首尾添加空白符。
簡單來說,就是不用賦值。
2.10、減少標籤的數量
編寫 HTML 代碼時,儘量避免多餘的父元素。
2.11、減少 JavaScript 生成的標籤
通過 JavaScript 生成的標籤讓內容變得不易查找、編輯,並且降低性能。能避免時儘量避免。
2.12、提示
儘量遵循 HTML 標準和語義,但是不要以犧牲實用性爲代價。任何時候都要儘量使用最少的標籤並保持最小的複雜度。
(三) CSS 規範
3.1、命名
- 類名使用小寫字母,以中劃線分隔
- id 採用駝峯式命名
id 和 class 的名稱使用可以反應元素目的和用途的名稱,或其他通用的名稱,代替表象和晦澀難懂的名稱
不推薦:
.fw-800 {
font-weight: 800;
}
.red {
color: red;
}
推薦:
.heavy {
font-weight: 800;
}
.important {
color: red;
}
3.2、選擇器
1)、css 選擇器中避免使用標籤名
從結構、表現、行爲分離的原則來看,應該儘量避免 css 中出現 HTML 標籤,並且在 css 選擇器中出現標簽名會存在潛在的問題。
2)、很多前端開發人員寫選擇器鏈的時候不使用 直接子選擇器(注:直接子選擇器和後代選擇器的區別)。有時,這可能會導致疼痛的設計問題並且有時候可能會很耗性能。然而,在任何情況下,這是一個非常不好的做法。如果你不寫很通用的,需要匹配到 DOM 末端的選擇器, 你應該總是考慮直接子選擇器。
不推薦:
.content .title {
font-size: 2rem;
}
推薦:
.content > .title {
font-size: 2rem;
}
3.3、儘量使用縮寫屬性
不推薦:
border-top-style: none;
font-family: palatino, georgia, serif;
font-size: 100%;
line-height: 1.6;
padding-bottom: 2em;
padding-left: 1em;
padding-right: 1em;
padding-top: 0;
推薦:
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;
3.4、選擇器及屬性獨佔一行
不推薦:
button {
width:100px;height:50px;color:#fff;background:#00a0e9;
}
推薦:
button {
width:100px;
height:50px;
color:#fff;
background:#00a0e9;
}
3.5、省略0後面的單位
不推薦:
div {
padding-bottom: 0px;
margin: 0em;
}
推薦:
div {
padding-bottom: 0;
margin: 0;
}
3.6、避免使用ID選擇器
不推薦:
#xiaoming {
padding-bottom: 0px;
margin: 0em;
}
推薦:
.xiaoming {
padding-bottom: 0px;
margin: 0em;
}
3.7、分號結尾
所有聲明語句都應當以分號結尾。最後一條聲明語句後面的分號是可選的,但是,如果省略這個分號,你的代碼可能更易出錯
3.8、省略 0.X前面的0
對於屬性值或顏色參數,省略小於 1 的小數前面的 0
例
.xiaoming {
box-shadow: 0 1px 1px 1px rgba(0, 0, 0, .5);
}
3.9、十六進制值全部小寫
1)、十六進制值應該全部小寫,例如,#fff。在掃描文檔時,小寫字符易於分辨,因爲他們的形式更易於區分
2)、儘量使用簡寫形式的十六進制值,例如,用 #fff 代替 #ffffff
3.10、屬性聲明順序
(1)文檔流相關屬性(display, position, float, clear, visibility, table-layout)
(2)盒模型相關屬性(width, height, margin, padding, border)
(3)排版相關屬性(font, line-height, text-align, text-indent, vertical-align)
(4)裝飾性相關屬性(color, background, opacity, cursor)
(5)文字排版(font, line-height, letter-spacing, color- text-align)
(6)生成內容相關屬性(background, border)
說明、
-
上面並沒有列舉涵蓋所有的屬性,只是一部分
-
分類之間使用一個空行分隔
-
並不一定嚴格遵循上述原則,因爲這是一個最佳實踐,與標準和性能無關
例子
.xiaoming {
/* 全局屬性 */
display: block;
float: none;
list-style: none;
/* 定位屬性 */
position: absolute;
left: 0;
top: 0;
right: 0;
bottom: 0;
z-index: 0;
/* 基本屬性 */
box-sizing: border-box;
margin: 0 auto;
padding: 0;
width: inherit;
min-width: none;
max-width: none;
height: inherit;
min-height: inherit;
max-height: none;
border: none;
border-radius: inherit;
/* 基礎效果屬性 */
font: '微軟雅黑';
font-size: 12px;
font-style: inherit;
font-family: 'new york';
font-weight: bold;
line-height: 32px;
text-align: center;
vertical-align: middle;
white-space: normal;
letter-spacing: normal;
word-spacing: normal;
word-break: break-all;
/* 背景屬性 */
color: #000000;
background: no-repeat;
background-clip: inherit;
background-color: #000000;
background-origin: border-box;
background-size: cover;
background-position: left top;
/* 渲染效果屬性 */
opacity: inherit;
outline: none;
box-shadow: none;
transition: all;
transform: inherit;
animation: .25s, 100ms;
/* 其他屬性 */
cursor: pointer;
}
3.11、重置樣式
css重置樣式主要是爲了讓各個瀏覽器的CSS樣式有一個統一的基準,使HTML元素樣式在跨瀏覽器時有一致性的效果。
備註:瀏覽器的兼容問題,不同瀏覽器對有些標籤的默認值是不同的,如果不對css初始化往往會出現瀏覽器之間的頁面顯示差異。但是初始化樣式也會對SEO有一定的影響,故初始化時儘量使影響最小。
/* 淘寶的重置樣式代碼 */
body, h1, h2, h3, h4, h5, h6, hr, p, blockquote, dl, dt, dd, ul, ol, li, pre, form, fieldset, legend, button, input, textarea, th, td { margin:0; padding:0; }
body, button, input, select, textarea { font:12px/1.5tahoma, arial, \5b8b\4f53; }
h1, h2, h3, h4, h5, h6{ font-size:100%; }
address, cite, dfn, em, var { font-style:normal; }
code, kbd, pre, samp { font-family:couriernew, courier, monospace; }
small{ font-size:12px; }
ul, ol { list-style:none; }
a { text-decoration:none; }
a:hover { text-decoration:underline; }
sup { vertical-align:text-top; }
sub{ vertical-align:text-bottom; }
legend { color:#000; }
fieldset, img { border:0; }
button, input, select, textarea { font-size:100%; }
table { border-collapse:collapse; border-spacing:0; }
(四)JavaScript規範
4.1、命名
1) 、採用小寫駝峯命名 lowerCamelCase,代碼中的命名均不能以下劃線開始,也不能以下劃線或美元符號結束
反例: _name / name_ / name$
2) 、方法名、參數名、成員變量、局部變量都統一使用 lowerCamelCase 風格,必須遵從駝峯形式。
正例: localValue / getHttpMessage() / inputUserId
其中 method 方法命名必須是 動詞 或者 動詞+名詞 形式
正例:saveShopCarData /openShopCarInfoDialog
反例:save / open / show / go
特此說明,增刪查改,詳情統一使用如下 4個單詞,不得使用其他(目的是爲了統一各個端)
add / delete / update / get
附: 函數方法常用的動詞:
get 獲取/set 設置,
add 增加/remove 刪除
create 創建/destory 移除
start 啓動/stop 停止
open 打開/close 關閉,
read 讀取/write 寫入
load 載入/save 保存,
create 創建/destroy 銷燬
begin 開始/end 結束,
backup 備份/restore 恢復
import 導入/export 導出,
split 分割/merge 合併
inject 注入/extract 提取,
attach 附着/detach 脫離
bind 綁定/separate 分離,
view 查看/browse 瀏覽
edit 編輯/modify 修改,
select 選取/mark 標記
copy 複製/paste 粘貼,
undo 撤銷/redo 重做
insert 插入/delete 移除,
add 加入/append 添加
clean 清理/clear 清除,
index 索引/sort 排序
find 查找/search 搜索,
increase 增加/decrease 減少
play 播放/pause 暫停,
launch 啓動/run 運行
compile 編譯/execute 執行,
debug 調試/trace 跟蹤
observe 觀察/listen 監聽,
build 構建/publish 發佈
input 輸入/output 輸出,
encode 編碼/decode 解碼
encrypt 加密/decrypt 解密,
compress 壓縮/decompress 解壓縮
pack 打包/unpack 解包,
parse 解析/emit 生成
connect 連接/disconnect 斷開,
send 發送/receive 接收
download 下載/upload 上傳,
refresh 刷新/synchronize 同步
update 更新/revert 復原,
lock 鎖定/unlock 解鎖
check out 簽出/check in 簽入,
submit 提交/commit 交付
push 推/pull 拉,
expand 展開/collapse 摺疊
begin 起始/end 結束,
start 開始/finish 完成
enter 進入/exit 退出,
abort 放棄/quit 離開
obsolete 廢棄/depreciate 廢舊,
collect 收集/aggregate 聚集
3) 、常量命名全部大寫,單詞間用下劃線隔開,力求語義表達完整清楚,不要嫌名字長。
正例: MAX_STOCK_COUNT
反例: MAX_COUNT
4.2、代碼格式
1) 、使用 2 個空格進行縮進
正例:
if (x < y) {
x += 10;
} else {
x += 1;
}
2)、 不同邏輯、不同語義、不同業務的代碼之間插入一個空行分隔開來以提升可讀性。
說明:任何情形,沒有必要插入多個空行進行隔開。
4.3 、字符串
統一使用單引號(‘),不使用雙引號(“)。這在js中創建 HTML 字符串非常有好處:
正例:
let str = 'foo';
let testDiv = '<div id="test"></div>';
反例:
let str = 'foo';
let testDiv = "<div id='test'></div>";
4.4、對象聲明
1)、使用字面值創建對象
正例: let user = {};
反例: let user = new Object();
2) 、使用字面量來代替對象構造器
正例:
var user = {
age: 0,
name: 1,
city: 3
};
反例:
var user = new Object();
user.age = 0;
user.name = 0;
user.city = 0;
4.5、使用 ES6,7
必須優先使用 ES6,7 中新增的語法糖和函數。這將簡化你的程序,並讓你的代碼更加靈活和可複用。
必須強制使用 ES6, ES7 的新語法,比如箭頭函數、await/async , 解構, let , for…of 等等
4.6、括號
下列關鍵字後必須有大括號(即使代碼塊的內容只有一行):if, else, for, while, do, switch, try, catch, finally, with。
正例:
if (condition) {
doSomething();
}
反例:
if (condition) doSomething();
4.7、分號
每句代碼後(必須)加";"
4.8、空格
-
左括號和後一個字符之間不出現空格;同樣,右括號和前一個字符之間也不出現空格
-
if/for/while/do 等保留字與左右括號之間都**
(必須)
**加空格,switch後無需加空格 -
function 後**
(必須)
加空格,參數的反括號後(必須)
**加空格 -
聲明變量
=
前後**(必須)
**添加空格 -
每個
;
後**(必須)
**加空格 -
任何運算符左右必須加一個空格。 說明:運算符包括賦值運算符=、邏輯運算符&&、加減乘除符號、三目運行符等
function add(xiaoming) { if (typeof xiaoming === 'undefined') { // code } }
4.9、undefined 判斷
永遠不要直接使用 undefined 進行變量判斷;使用 typeof 和字符串’undefined’對變量進行判斷。
正例:
if (typeof person === 'undefined') {
...
}
反例:
if (person === undefined) {
...
}
4.10、條件判斷和循環最多三層
條件判斷能使用三目運算符和邏輯運算符解決的,就不要使用條件判斷,但是謹記不要寫太長的三目運算符。如果超過 3 層請抽成函數,並寫清楚註釋。
4.11、慎用 console.log
因 console.log 大量使用會有性能問題,所以在非 webpack 項目中謹慎使用 log 功能