這是一份旨在加強團隊的開發協做,提升代碼質量和打造開發基石的編碼風格規範,其中包含了 HTML, JavaScript 和 CSS/SCSS 這幾個部分。咱們知道,當一個團隊開始指定並實行編碼規範的話,錯誤就會變得更加顯而易見。若是一段特定的代碼不符合規範的話,它有可能只是代碼風格錯誤,而也有可能會是 bug。早期指定規範就使得代碼審覈得以更好的開展,而且能夠更精確的地定位到錯誤。只要開發者們可以保證源代碼源文件都嚴格遵循規範,那接下去所使用的混淆、壓縮和編譯工具則可投其所好不盡相同。但願各位同事嚴格之前端規範文檔要求本身。javascript
** 最新修改於 2019年06月26日 10:30 **css
參考原文:Web Styleguide – Style guide to harmonize HTML, Javascript and CSS / SASS coding stylehtml
如下章節列舉了一些可應用在 HTML, JavaScript 和 CSS/SCSS 上的通用規則。前端
在 web 項目中,全部的文件名應該都遵循同一命名約定。以可讀性而言,減號(-)是用來分隔文件名的不二之選。同時它也是常見的 URL 分隔符(i.e. //example.com/blog/my-blog-entry
or //s.example.com/images/big-black-background.jpg
),因此理所固然的,減號應該也是用來分隔資源名稱的好選擇。 請確保文件命名老是以字母開頭而不是數字。而以特殊字符開頭命名的文件,通常都有特殊的含義與用處(i.e. _ __ )。 資源的字母名稱必須全爲小寫,這是由於在某些對大小寫字母敏感的操做系統中,當文件經過工具壓縮混淆後,或者人爲修改事後,大小寫不一樣而致使引用文件不一樣的錯誤,很難被發現。 還有一些狀況下,須要對文件增長先後綴或特定的擴展名(好比 .min.js, .min.css
),抑或一串前綴(好比 3fa89b.main.min.css
)。這種狀況下,建議使用點分隔符來區分這些在文件名中帶有清晰意義的元數據。java
MyScript.js
myCamelCaseName.css
i_love_underscores.html
1001-scripts.js
my-file-min.css
複製代碼
my-script.js
my-camel-case-name.css
i-love-underscores.html
thousand-and-one-scripts.js
my-file.min.css
複製代碼
不要指定引入資源所帶的具體協議。git
當引入圖片或其餘媒體文件,還有樣式和腳本時,URLs 所指向的具體路徑,不要指定協議部分(http:
, https:
),除非這二者協議都不可用。github
不指定協議使得 URL 從絕對的獲取路徑轉變爲相對的,在請求資源協議沒法肯定時很是好用,並且還能爲文件大小節省幾個字節。web
<script src="http://cdn.com/foundation.min.js"></script>
<script src="https://cdn.com/foundation.min.js"></script>
複製代碼
<script src="//cdn.com/foundation.min.js"></script>
複製代碼
.example {
background: url(http://static.example.com/images/bg.jpg);
background: url(https://static.example.com/images/bg.jpg);
}
複製代碼
.example {
background: url(//static.example.com/images/bg.jpg);
}
複製代碼
一次縮進四個空格。習慣用tab鍵可使用IDE自動轉換成空格。編程
<ul>
<li>Fantastic</li>
<li>Great</li>
<li>
<a href="#">Test</a>
</li>
</ul>
複製代碼
@media screen and (min-width: 1100px) {
body {
font-size: 100%;
}
}
複製代碼
(function(){
var x = 10;
function y(a, b) {
return {
result: (a + b) * x
}
}
}());
複製代碼
註釋是你本身與你的小夥伴們瞭解代碼寫法和目的的惟一途徑。特別是在寫一些看似瑣碎的可有可無的代碼時,因爲記憶點不深入,註釋就變得尤其重要了。 註釋也能讓你和同事們更加快捷瞭解代碼塊的模塊功能數組
推薦使用 HTML5 的文檔類型申明: <!DOCTYPE html>
. (建議使用 text/html 格式的 HTML。避免使用 XHTML。XHTML 以及它的屬性,好比 application/xhtml+xml
在瀏覽器中的應用支持與優化空間都十分有限)。
HTML 中最好不要將無內容元素的標籤閉合,例如:使用 <br>
而非 <br />
.(i.e. area
, base
, br
, col
, command
, embed
, hr
, img
, input
, keygen
, link
, meta
, param
, source
, track
, wbr
)
通常狀況下,建議使用能經過標準規範驗證的 HTML 代碼,除非在性能優化和控制文件大小上不得不作出讓步。 規範化的 HTML 是顯現技術要求與侷限的顯著質量基線,它促進了 HTML 被更好地運用。
<title>Test</title>
<article>This is only a test.
複製代碼
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>
複製代碼
HTML5 規範中規定了 HTML 標籤是能夠省略的。但從可讀性來講,在開發的源文件中最好不要這樣作,由於省略標籤可能會致使一些問題。
省略一些可選的標籤確實使得頁面大小減小,這頗有用,尤爲是對於一些大型網站來講。爲了達到這一目的,咱們能夠在開發後期對頁面進行壓縮處理,在這個環節中這些可選的標籤徹底就能夠省略掉了。
出於性能考慮,腳本異步加載很關鍵。一段腳本放置在 <head>
內,好比 <script src="main.js"></script>
,其加載會一直阻塞 DOM 解析,直至它徹底地加載和執行完畢。這會形成頁面顯示的延遲。特別是一些重量級的腳本,對用戶體驗來講那真是一個巨大的影響。 異步加載腳本可緩解這種性能影響。若是隻需兼容 IE10+,可將 HTML5 的 async
屬性加至腳本中,它可防止阻塞 DOM 的解析,甚至你能夠將腳本引用寫在 <head>
裏也沒有影響。
<html>
<head>
<link rel="stylesheet" href="main.css">
</head>
<body>
<!-- body goes here -->
<script src="main.js" async></script>
</body>
</html>
複製代碼
<html>
<head>
<link rel="stylesheet" href="main.css">
<script src="main.js" async></script>
</head>
<body>
<!-- body goes here -->
</body>
</html>
複製代碼
根據元素(有時被錯誤地稱做「標籤」)其被創造出來時的初始意義來使用它。打個比方,用 header 元素來定義頭部標題,p 元素來定義文字段落,用 a 元素來定義連接錨點,等等。
有根據有目的地使用 HTML 元素,對於可訪問性、代碼重用、代碼效率來講意義重大。書寫html代碼時應避免通篇div元素。
<header>
<h1>My page title</h1>
</header>
<nav class="top-navigation">
<ul>
<li class="nav-item"><a href="#home">Home</a></li>
<li class="nav-item"><a href="#news">News</a></li>
<li class="nav-item"><a href="#about">About</a></li>
</ul>
</nav>
<main class="news-page" role="main">
<section class="page-section news">
<header>
<h2 class="title">All news articles</h2>
</header>
<article class="news-article">
<header>
<div class="article-title">Good article</div>
<small class="intro">Introduction sub-title</small>
</header>
<div class="content">
<p>This is a good example for HTML semantics</p>
</div>
<aside class="article-side-notes">
<p>I think I'm more on the side and should not receive the main credits</p>
</aside>
<footer class="article-foot-notes">
<p>This article was created by David <time datetime="2014-01-01 00:00" class="time">1 month ago</time></p>
</footer>
</article>
<footer class="section-footer">
<p>Related sections: Events, Public holidays</p>
</footer>
</section>
</main>
<footer class="page-footer">
Copyright 2014
</footer>
複製代碼
理解 web 中如何和爲什麼區分不一樣的關注點,這很重要。這裏的關注點主要指的是:信息(HTML 結構)、外觀(CSS)和行爲(JavaScript)。爲了使它們成爲可維護的乾淨整潔的代碼,咱們要儘量的將它們分離開來。
嚴格地保證結構、表現、行爲三者分離,並儘可能使三者之間沒有太多的交互和聯繫。
就是說,儘可能在文檔和模板中只包含結構性的 HTML;而將全部表現代碼,移入樣式表中;將全部動做行爲,移入腳本之中。
在此以外,爲使得它們之間的聯繫儘量的小,在文檔和模板中也儘可能少地引入樣式和腳本文件。
清晰的分層意味着,實際開發項目中應儘可能參照一下標準:
<style>.no-good {}</style>
)<hr style="border-top: 5px solid black">
)<script>alert('no good')</script>
)<b>
, <u>
, <center>
, <font>
, <b>
)<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="base.css">
<link rel="stylesheet" href="grid.css">
<link rel="stylesheet" href="type.css">
<link rel="stylesheet" href="modules/teaser.css">
</head>
<body>
<h1 style="font-size: 3rem"></h1>
<b>I'm a subtitle and I'm bold!</b>
<center>Dare you center me!</center>
<script> alert('Just dont...'); </script>
<div class="red">I'm important!</div>
</body>
</html>
複製代碼
<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="main.css">
</head>
<body>
<h1 class="title"></h1>
<div class="sub-title">I'm a subtitle and I'm bold!</div>
<span class="comment">Dare you center me!</span>
what you want to do with it -->
<div class="important">I'm important!</div>
<script async src="main.js"></script>
</body>
</html>
複製代碼
不要讓非內容信息污染了你的 HTML。如今貌似有一種傾向:經過 HTML 來解決設計問題,這是顯然是不對的。HTML 就應該只關注內容。
HTML 標籤的目的,就是爲了避免斷地展現內容信息。 * 不要引入一些特定的 HTML 結構來解決一些視覺設計問題 * 不要將 img 元素當作專門用來作視覺設計的元素 如下例子展現了誤將 HTML 用來解決設計問題的這兩種狀況:
<span class="text-box">
<span class="square"></span>
See the square next to me?
</span>
複製代碼
.text-box > .square {
display: inline-block;
width: 1rem;
height: 1rem;
background-color: red;
}
複製代碼
<span class="text-box">
See the square next to me?
</span>
複製代碼
.text-box::before {
content: "";
display: inline-block;
width: 1rem;
height: 1rem;
background-color: red;
}
複製代碼
一般一個比較好的作法是將頁面內全部的頭部標題元素都加上 ID. 這樣作,頁面 URL 的 hash 中帶上對應的 ID 名稱,即造成描點,方便跳轉至對應元素所處位置。
打個比方,當你在瀏覽器中輸入 URL http://your-site.com/about#best-practices
,瀏覽器將定位至如下 H3 上。
<h3 id="best-practices">Best practices</h3>
複製代碼
在每個塊狀元素,列表元素和表格元素後,加上一新空白行,並對其子孫元素進行縮進。內聯元素寫在一行內,塊狀元素還有列表和表格要另起一行。
(若是因爲換行的空格引起了不可預計的問題,那將全部元素併入一行也是能夠接受的,格式警告總好過錯誤警告)。
<blockquote>
<p><em>Space</em>, the final frontier.</p>
</blockquote>
<ul>
<li>Moe</li>
<li>Larry</li>
<li>Curly</li>
</ul>
<table>
<thead>
<tr>
<th scope="col">Income</th>
<th scope="col">Taxes</th>
</tr>
</thead>
<tbody>
<tr>
<td>$ 5.00</td>
<td>$ 4.50</td>
</tr>
</tbody>
</table>
複製代碼
使用雙引號(" ") 而不是單引號(' ') 。
<div class='news-article'></div>
複製代碼
<div class="news-article"></div>
複製代碼
ID和class(類)名老是使用能夠反應元素目的和用途的名稱,或其餘通用名稱。代替表象和晦澀難懂的名稱。
應該首選具體和反映元素目的的名稱,由於這些是最能夠理解的,並且發生變化的可能性最小。
通用名稱只是多個元素的備用名,他們兄弟元素之間是同樣的,沒有特別意義。 區分他們,使他們具備特殊意義,一般須要爲「幫手」。
儘管class(類)名和ID 的語義化對於計算機解析來講沒有什麼實際的意義, 語義化的名稱 一般是正確的選擇,由於它們所表明的信息含義,不包含表現的限制。
.fw-800 {
font-weight: 800;
}
.red {
color: red;
}
複製代碼
.heavy {
font-weight: 800;
}
.important {
color: red;
}
複製代碼
通常狀況下ID不該該被應用於樣式。 ID的樣式不能被複用而且每一個頁面中你只能使用一次ID。 使用ID惟一有效的是肯定網頁或整個站點中的位置。 儘管如此,你應該始終考慮使用class,而不是id,除非只使用一次。
#content .title {
font-size: 2em;
}
複製代碼
.content .title {
font-size: 2em;
}
複製代碼
另外一個反對使用ID的觀點是含有ID選擇器權重很高。 一個只包含一個ID選擇器權重高於包含1000個class(類)名的選擇器,這使得它很奇怪。
// 這個選擇器權重高於下面的選擇器
#content .title {
color: red;
}
// than this selector!
html body div.content.news-content .title.content-title.important {
color: blue;
}
複製代碼
當構建選擇器時應該使用清晰, 準確和有語義的class(類)名。不要使用標籤選擇器。 若是你只關心你的class(類)名,而不是你的代碼元素,這樣會更容易維護。
從分離的角度考慮,在表現層中不該該分配html標記/語義。 它多是一個有序列表須要被改爲一個無序列表,或者一個div將被轉換成article。 若是你只使用具備實際意義的class(類)名, 而且不使用元素選擇器,那麼你只須要改變你的html標記,而不用改動你的CSS。
div.content > header.content-header > h2.title {
font-size: 2em;
}
複製代碼
.content > .content-header > .title {
font-size: 2em;
}
複製代碼
CSS提供了各類縮寫屬性(如 font 字體)應該儘量使用,即便在只設置一個值的狀況下。
使用縮寫屬性對於代碼效率和可讀性是有頗有用的。
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;
複製代碼
省略「0」值後面的單位。不要在0值後面使用單位,除非有值。
padding-bottom: 0px;
margin: 0em;
複製代碼
padding-bottom: 0;
margin: 0;
複製代碼
在可能的狀況下,使用3個字符的十六進制表示法。 顏色值容許這樣表示, 3個字符的十六進制表示法更簡短。
始終使用小寫的十六進制數字。
color: #FF33AA;
複製代碼
color: #f3a;
複製代碼
使用連字符(中劃線)分隔ID和Class(類)名中的單詞。爲了加強課理解性,在選擇器中不要使用除了連字符(中劃線)覺得的任何字符(包括沒有)來鏈接單詞和縮寫。
另外,做爲該標準,預設屬性選擇器能識別連字符(中劃線)做爲單詞[attribute|=value]的分隔符, 因此最好的堅持使用連字符做爲分隔符。
.demoimage {}
.error_status {}
複製代碼
#video-id {}
.ads-sample {}
複製代碼
這是一個選擇器內書寫CSS屬性順序的大體輪廓。這是爲了保證更好的可讀性和可掃描重要。
做爲最佳實踐,咱們應該遵循如下順序(應該按照下表的順序):
.box {
font-family: 'Arial', sans-serif;
border: 3px solid #ddd;
left: 30%;
position: absolute;
text-transform: uppercase;
background-color: #eee;
right: 30%;
display: block;
font-size: 1.5rem;
overflow: hidden;
padding: 1em;
margin: 1em;
}
複製代碼
.box {
display: block;
position: absolute;
left: 30%;
right: 30%;
overflow: hidden;
margin: 1em;
padding: 1em;
background-color: #eee;
border: 3px solid #ddd;
font-family: 'Arial', sans-serif;
font-size: 1.5rem;
text-transform: uppercase;
}
複製代碼
爲了保證一致性和可擴展性,每一個聲明應該用分號結束,每一個聲明換行。
.test {
display: block; height: 100px
}
複製代碼
.test {
display: block;
height: 100px;
}
複製代碼
屬性名的冒號後使用一個空格。出於一致性的緣由, 屬性和值(但屬性和冒號之間沒有空格)的之間始終使用一個空格。
h3 {
font-weight:bold;
}
複製代碼
h3 {
font-weight: bold;
}
複製代碼
每一個選擇器和屬性聲明老是使用新的一行。
a:focus, a:active {
position: relative; top: 1px;
}
複製代碼
h1,
h2,
h3 {
font-weight: normal;
line-height: 1.2;
}
複製代碼
規則之間始終有一個空行(雙換行符)分隔。
html {
background: #fff;
}
body {
margin: auto;
width: 50%;
}
複製代碼
屬性選擇器或屬性值用雙引號(" "),而不是單引號(' ')括起來。 URI值(url())不要使用引號。
@import url('//cdn.com/foundation.css');
html {
font-family: 'open sans', arial, sans-serif;
}
body::after {
content: 'pause';
}
複製代碼
@import url(//cdn.com/foundation.css);
html {
font-family: "open sans", arial, sans-serif;
}
body::after {
content: "pause";
}
複製代碼
僞類選擇器使用一個冒號(:)(i.e. :first-letter
, :hover
, :active
etc) 僞類元素使用一個雙冒號(::)(i.e. ::before
and ::after
)
.button:hover {}
.content::before {}
複製代碼
在Less中你能夠嵌套選擇器,這可使代碼變得更清潔和可讀。嵌套全部的選擇器,但儘可能避免嵌套沒有任何內容的選擇器。 若是你須要指定一些子元素的樣式屬性,而父元素將不什麼樣式屬性, 可使用常規的CSS選擇器鏈。 這將防止您的腳本看起來過於複雜。 (Less 中 &
有鏈接的意思)
.content {
display: block;
}
.content > .news-article > .title {
font-size: 1.2em;
}
複製代碼
.content {
display: block;
& > .news-article {
& > .title {
font-size: 1.2em;
}
}
}
複製代碼
老是將代碼包裹成一個 IIFE(Immediately-Invoked Function Expression),用以建立獨立隔絕的定義域。這一舉措可防止全局命名空間被污染。
IIFE 還可確保你的代碼不會輕易被其它全局命名空間裏的代碼所修改(i.e. 第三方庫,window 引用,被覆蓋的未定義的關鍵字等等)。
var x = 10,
y = 100;
console.log(window.x + ' ' + window.y);
複製代碼
(function(log, w, undefined){
'use strict';
var x = 10,
y = 100;
log((w.x === undefined) + ' ' + (w.y === undefined));
}(window.console.log, window));
複製代碼
不管什麼時候,想要建立一個新的封閉的定義域,那就用 IIFE。它不只避免了干擾,也使得內存在執行完後當即釋放。
全部腳本文件建議都從 IIFE 開始。
當即執行的函數表達式的執行括號應該寫在外包括號內。雖然寫在內仍是寫在外都是有效的,但寫在內使得整個表達式看起來更像一個總體,所以推薦這麼作。
(function(){})();
複製代碼
(function(){}());
複製代碼
so,用下列寫法來格式化你的 IIFE 代碼:
(function(){
'use strict';
// Code goes here
}());
複製代碼
若是你想引用全局變量或者是外層 IIFE 的變量,能夠經過下列方式傳參:
(function($, w, d){
'use strict';
$(function() {
w.alert(d.querySelectorAll('div').length);
});
}(jQuery, window, document));
複製代碼
建議使用 ECMA Script 5 中新增的語法糖和函數。這將簡化你的程序,並讓你的代碼更加靈活和可複用。
ECMAScript 5 嚴格模式可在整個腳本或獨個方法內被激活。它對應不一樣的 javascript 語境會作更加嚴格的錯誤檢查。嚴格模式也確保了 javascript 代碼更加的健壯,運行的也更加快速。
嚴格模式會阻止使用在將來極可能被引入的預留關鍵字。
你應該在你的腳本中啓用嚴格模式,最好是在獨立的 IIFE 中應用它。避免在你的腳本第一行使用它而致使你的全部腳本都啓動了嚴格模式,這有可能會引起一些第三方類庫的問題。
// Script starts here
'use strict';
(function(){
// Your code starts here
}());
複製代碼
(function(){
'use strict';
// Your code starts here
}());
複製代碼
老是使用 var 來聲明變量。如不指定 var,變量將被隱式地聲明爲全局變量,這將對變量難以控制。若是沒有聲明,變量處於什麼定義域就變得不清(能夠是在 Document 或 Window 中,也能夠很容易地進入本地定義域)。因此,請老是使用 var 來聲明變量。
採用嚴格模式帶來的好處是,當你手誤輸入錯誤的變量名時,它能夠經過報錯信息來幫助你定位錯誤出處。
x = 10;
y = 100;
複製代碼
var x = 10,
y = 100;
複製代碼
把賦值儘可能寫在變量申明中。
var a,
b,
c;
a = 10;
b = 10;
c = 100;
複製代碼
var a = 10,
b = 10,
c = 100;
複製代碼
eval()
不但混淆語境還很危險,總會有比這更好、更清晰、更安全的另外一種方案來寫你的代碼,所以儘可能不要使用 evil 函數。
switch 語句主要是爲避免讓開發者編寫下面的代碼:
if (i == 20)
alert("20");
else if (i == 30)
alert("30");
else if (i == 40)
alert("40");
else
alert("other");
複製代碼
switch (i) {
case 20: alert("20");
break;
case 30: alert("30");
break;
case 40: alert("40");
break;
default: alert("other");
}
複製代碼
用數組和對象字面量來代替數組和對象構造器。數組構造器很容易讓人在它的參數上犯錯。
var a1 = new Array(x1, x2, x3);
var o2 = new Object();
o2.a = 0;
o2.b = 1;
o2.c = 2;
o2['strange key'] = 3;
複製代碼
var a = [x1, x2, x3];
var o2 = {
a: 0,
b: 1,
c: 2,
'strange key': 3
};
複製代碼
統一使用單引號(‘),不使用雙引號(「)。這在建立 HTML 字符串很是有好處:
var msg = 'This is some HTML <div class="makes-sense"></div>';
複製代碼
用三元操做符分配或返回語句。在比較簡單的狀況下使用,避免在複雜的狀況下使用。沒人願意用 10 行三元操做符把本身的腦子繞暈。
if (x === 10) {
return 'valid';
} else {
return 'invalid';
}
複製代碼
return x === 10 ? 'valid' : 'invalid';
複製代碼
切勿在語句塊內聲明函數,在 ECMAScript 5 的嚴格模式下,這是不合法的。函數聲明應該在定義域的頂層。但在語句塊內可將函數申明轉化爲函數表達式賦值給變量。
if (x) {
function foo() {}
}
複製代碼
if (x) {
var foo = function() {};
}
複製代碼
JavaScript 中語句要以分號結束,不然它將會繼續執行下去,無論換不換行。 分號須要用在表達式的結尾,而並不是函數聲明的結尾。區分它們最好的例子是:
var foo = function() {
return true;
}; // semicolon here.
function foo() {
return true;
} // no semicolon here.
複製代碼