Google HTML/CSS/JS代碼風格指南

時間 2019-12-12

標籤 google html css 代碼風格指南欄目 Google 简体版

原文原文鏈接

JS版本參見：http://www.zhangxinxu.com/wordpress/2012/07/google-html-css-javascript-style-guides/

HTML/CSS修正版本 2.1

背景

本文檔定義了HTML/CSS的編寫格式和風格規則。它旨在提升合做和代碼質量,並使其支持基礎架構。適用於HTML/CSS文件，包括GSS文件。只要代碼質量是能夠被維護的，就能很好的被工具混淆、壓縮和合並。javascript

樣式規則

協議

嵌入式資源書寫省略協議頭

省略圖像、媒體文件、樣式表和腳本等URL協議頭部聲明 ( http: , https: )。若是不是這兩個聲明的URL則不省略。css

省略協議聲明，使URL成相對地址，防止內容混淆問題和致使小文件重複下載。html

<!-- 不推薦 -->
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>

<!-- 推薦 -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

/* 不推薦 */
.example {
  background: url(http://www.google.com/images/example);
}

/* 推薦 */
.example {
  background: url(//www.google.com/images/example);
}

排版規則

縮進

每次縮進兩個空格。

不要用TAB鍵或多個空格來進行縮進。java

<ul>
  <li>Fantastic
  <li>Great
</ul>

.example {
  color: blue;
}

大小寫

只用小寫字母。

全部的代碼都用小寫字母：適用於元素名，屬性，屬性值（除了文本和 CDATA ），選擇器，特性，特性值（除了字符串）。web

<!-- 不推薦 -->
<A HREF="/">Home</A>

<!-- 推薦 -->
<img src="google.png" alt="Google">

行尾空格

刪除行尾白空格。

行尾空格不必存在。canvas

<!-- 不推薦 -->
<p>What?_

<!-- 推薦 -->
<p>Yes please.

元數據規則

編碼

用不帶BOM頭的 UTF-8編碼。

讓你的編輯器用沒有字節順序標記的UTF-8編碼格式進行編寫。api

在HTML模板和文件中指定編碼 <meta charset="utf-8"> . 不須要制定樣式表的編碼，它默認爲UTF-8.瀏覽器

（更多有關於編碼的信息和怎樣指定它，請查看 Character Sets & Encodings in XHTML, HTML and CSS。）架構

註釋

儘量的去解釋你寫的代碼。

用註釋來解釋代碼：它包括什麼，它的目的是什麼，它能作什麼，爲何使用這個解決方案，仍是說只是由於偏心如此呢？app

（本規則可選，不必每份代碼都描述的很充分，它會增重HTML和CSS的代碼。這取決於該項目的複雜程度。）

活動的條目

用 TODO 標記代辦事項和正活動的條目

只用 TODO 來強調代辦事項，不要用其餘的常見格式，例如 @@ 。

附加聯繫人（用戶名或電子郵件列表），用括號括起來，例如 TODO(contact) 。

可在冒號以後附加活動條目說明等，例如 TODO: 活動條目說明 。

{# TODO(cha.jn): 從新置中 #}
<center>Test</center>

<!-- TODO: 刪除可選元素 -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

HTML代碼風格規則

文檔類型

請使用HTML5標準。

HTML5是目前全部HTML文檔類型中的首選： <!DOCTYPE html> .

（推薦用HTML文本文檔格式，即 text/html . 不要用 XHTML。 XHTML格式，即 application/xhtml+xml , 有倆瀏覽器徹底不支持，還比HTML用更多的存儲空間。）

HTML代碼有效性

儘可能使用有效的HTML代碼。

編寫有效的HTML代碼，不然很難達到性能上的提高。

用相似這樣的工具 W3C HTML validator 來進行測試。

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>

語義

根據HTML各個元素的用途而去使用它們。

使用元素 (有時候錯稱其爲「標籤」) 要知道爲何去使用它們和是否正確。例如，用heading元素構造標題， p 元素構造段落, a 元素構造錨點等。

根據HTML各個元素的用途而去使用是很重要的，它涉及到文檔的可訪問性、重用和代碼效率等問題。

<!-- 不推薦 -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- 推薦 -->
<a href="recommendations/">All recommendations</a>

多媒體後備方案

爲多媒體提供備選內容。

對於多媒體，如圖像，視頻，經過 canvas 讀取的動畫元素，確保提供備選方案。對於圖像使用有意義的備選文案（ alt ）對於視頻和音頻使用有效的副本和文案說明。

提供備選內容是很重要的，緣由：給盲人用戶以一些提示性的文字，用 @alt 告訴他這圖像是關於什麼的，給可能沒理解視頻或音頻的內容的用戶以提示。

（圖像的 alt 屬性會產生冗餘，若是使用圖像只是爲了避免能當即用CSS而裝飾的，就不須要用備選文案了，能夠寫 alt="" 。）

<!-- 不推薦 -->
<img src="spreadsheet.png">

<!-- 推薦 -->
<img src="spreadsheet.png" alt="電子表格截圖">

關注點分離

將表現和行爲分開。

嚴格保持結構（標記），表現（樣式），和行爲（腳本）分離, 並儘可能讓這三者之間的交互保持最低限度。

確保文檔和模板只包含HTML結構，把全部表現都放到樣式表裏，把全部行爲都放到腳本里。

此外，儘可能使腳本和樣式表在文檔與模板中有最小接觸面積，即減小外鏈。

將表現和行爲分開維護是很重要滴，由於更改HTML文檔結構和模板會比更新樣式表和腳本更花費成本。

<!-- 不推薦 -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
  <u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
  my website without doing everything all over again!</center>

<!-- 推薦 -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
  doing it: separating concerns and avoiding anything in the HTML of
  my website that is presentational.
<p>It’s awesome!

實體引用

不要用實體引用。

不須要使用相似 — 、 ” 和 ☺ 等的實體引用, 假定團隊之間所用的文件和編輯器是同一編碼（UTF-8）。

在HTML文檔中具備特殊含義的字符（例如 < 和 & )爲例外，噢對了，還有「不可見」字符（例如no-break空格）。

<!-- 不推薦 -->
歐元貨幣符號是 &ldquo;&eur;&rdquo;。

<!-- 推薦 -->
歐元貨幣符號是 「€」。

可選標籤

省略可選標籤（可選）。

出於優化文件大小和校驗，能夠考慮省略可選標籤，哪些是可選標籤能夠參考 HTML5 specification。

（這種方法可能須要更精準的規範來制定，衆多的開發者對此的觀點也都不一樣。考慮到一致性和簡潔的緣由，省略全部可選標記是有必要的。）

<!-- 不推薦 -->
<!DOCTYPE html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>

<!-- 推薦 -->
<!DOCTYPE html>
<title>Saving money, saving bytes</title>
<p>Qed.

type屬性

在樣式表和腳本的標籤中忽略 type 屬性

在樣式表（除非不用 CSS）和腳本（除非不用 JavaScript）的標籤中不寫 type 屬性。

HTML5默認 type 爲 text/css 和 text/javascript 類型，因此不必指定。即使是老瀏覽器也是支持的。

<!-- 不推薦 -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
  type="text/css">

<!-- 推薦 -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">

<!-- 不推薦 -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
  type="text/javascript"></script>

<!-- 推薦 -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

HTML代碼格式規則

格式

每一個塊元素、列表元素或表格元素都獨佔一行，每一個子元素都相對於父元素進行縮進。

獨立元素的樣式（as CSS allows elements to assume a different role per display property), 將塊元素、列表元素或表格元素都放在新行。

另外，須要縮進塊元素、列表元素或表格元素的子元素。

（若是出現了列表項左右空文本節點問題，能夠試着將全部的 li 元素都放在一行。 A linter is encouraged to throw a warning instead of an error.)

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe
  <li>Larry
  <li>Curly
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income
      <th scope="col">Taxes
  <tbody>
    <tr>
      <td>$ 5.00
      <td>$ 4.50
</table>

CSS代碼風格規則

CSS代碼有效性

儘可能使用有效的CSS代碼。

使用有效的CSS代碼，除非是處理CSS校驗器程序錯誤或者須要專有語法。

用相似W3C CSS validator 這樣的工具來進行有效性的測試。

使用有效的CSS是重要的質量衡量標準，若是發現有的CSS代碼沒有任何效果的能夠刪除，確保CSS用法適當。

ID和class的命名

爲ID和class取通用且有意義的名字。

應該從ID和class的名字上就能看出這元素是幹嗎用的，而不是表象或模糊不清的命名。

應該優先慮以這元素具體目來進行命名，這樣他就最容易理解，減小更新。

通用名稱能夠加在兄弟元素都不特殊或沒有個別意義的元素上，能夠起名相似「helpers」這樣的泛。

使用功能性或通用的名字會減小沒必要要的文檔或模板修改。

/* 不推薦: 無心義 不易理解 */
#yee-1901 {}

/* 不推薦: 表達不具體 */
.button-green {}
.clear {}

/* 推薦: 明確詳細 */
#gallery {}
#login {}
.video {}

/* 推薦: 通用 */
.aux {}
.alt {}

ID和class命名風格

非必要的狀況下，ID和class的名稱應儘可能簡短。

簡要傳達ID或class是關於什麼的。

經過這種方式，似的代碼易懂且高效。

/* 不推薦 */
#navigation {}
.atr {}

/* 推薦 */
#nav {}
.author {}

類型選擇器

避免使用CSS類型選擇器。

非必要的狀況下不要使用元素標籤名和ID或class進行組合。

出於性能上的考慮避免使用父輩節點作選擇器 performance reasons.

/* 不推薦 */
ul#example {}
div.error {}

/* 推薦 */
#example {}
.error {}

屬性縮寫

寫屬性值的時候儘可能使用縮寫。

CSS不少屬性都支持縮寫shorthand （例如 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後面的單位。

非必要的狀況下 0 後面不用加單位。

margin: 0;
padding: 0;

0開頭的小數

省略0開頭小數點前面的0。

值或長度在-1與1之間的小數，小數前的 0 能夠忽略不寫。

font-size: .8em;

URI外的引號

省略URI外的引號。

不要在 url() 裏用 ( "" , '' ) 。

@import url(//www.google.com/css/go.css);

十六進制

十六進制儘量使用3個字符。

加顏色值時候會用到它，使用3個字符的十六進制更短與簡潔。

/* 不推薦 */
color: #eebbcc;

/* 推薦 */
color: #ebc;

前綴

選擇器前面加上特殊應用標識的前綴（可選）。

大型項目中最好在ID或class名字前加上這種標識性前綴（命名空間），使用短破折號連接。

使用命名空間能夠防止命名衝突，方便維護，好比在搜索和替換操做上。

.adw-help {} /* AdWords */
#maia-note {} /* Maia */

ID和class命名的定界符

ID和class名字有多單詞組合的用短破折號「-」分開。

別在選擇器名字裏用短破折號「-」之外的鏈接詞(包括啥也沒有)，以增進對名字的理解和查找。

/* 不推薦：「demo」和「image」中間沒加「-」 */
.demoimage {}

/* 不推薦：用下劃線「_」是屌絲的風格 */
.error_status {}

/* 推薦 */
#video-id {}
.ads-sample {}

Hacks

最好避免使用該死的CSS 「hacks」 —— 請先嚐試使用其餘的解決方法。

雖然它頗有誘惑力，能夠看成用戶代理檢測或特殊的CSS過濾器，但它的行爲太過於頻繁，會長期傷害項目的效率和代碼管理，因此能用其餘的解決方案就找其餘的。

CSS代碼格式規則

聲明順序

依字母順序進行聲明。

都按字母順序聲明，很容易記住和維護。

忽略瀏覽器的特定前綴排序，但多瀏覽器特定的某個CSS屬性前綴應相對保持排序（例如-moz前綴在-webkit前面）。

background: fuchsia;
border: 1px solid;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
border-radius: 4px;
color: black;
text-align: center;
text-indent: 2em;

代碼塊內容縮進

縮進全部代碼塊（「{}」之間）內容。

縮進全部代碼塊的內容，它可以提升層次結構的清晰度。

@media screen, projection {

  html {
    background: #fff;
    color: #444;
  }

}

聲明完結

全部聲明都要用「;」結尾。

考慮到一致性和拓展性，請在每一個聲明尾部都加上分號。

/* 不推薦 */
.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%;
}

CSS元數據規則

註釋部分

按組寫註釋。（可選）

若是能夠，按照功能的類別來對一組樣式表寫統一註釋。獨立成行。

/* Header */

#adw-header {}

/* Footer */

#adw-footer {}

/* Gallery */

.adw-gallery {}

吐槽部分

堅持一致原則

若是你要編輯代碼，先花幾分鐘看看它的代碼風格，若是它這麼作，那你也應該這麼作。

風格統一了，就有了一個共同思惟的環境，參與者就能夠專一的看你要說什麼，而不是先想你是在說哪星球的語言。雖然咱們在這裏提出統同樣式規則，但就只是想讓你們都知曉並借鑑而對本身的風格進行修正。固然，保持本身獨有的風格也是很重要的。balabala……

相關標籤/搜索

每日一句

每一个你不满意的现在，都有一个你没有努力的曾经。