谷歌HTML/CSS代码格式指导

背景介绍

This document defines formatting and style rules for HTML and
CSS. It aims at improving collaboration, code quality, and
enabling supporting infrastructure. It applies to raw,
working files that use HTML and CSS, including GSS
files. Tools are free to obfuscate, minify, and compile as
long as the general code quality is maintained.

通用代码格式规则

协议

省略掉协议名称。

Omit the protocol portion (http:, https:) from URLs pointing to images and other
media files, style sheets, and scripts unless the respective
files are not available over both protocols.

Omitting the protocol—which makes the URL
relative—prevents mixed content issues and results in
minor file size savings.

<!-- Not recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>

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

/* Not recommended */
.example {
  background: url(https://www.google.com/images/example);
}

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

通用代码格式化规则

缩进

一次缩进2个空格符

Don’t use tabs or mix tabs and spaces for indentation.

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

.example {
  color: blue;
}

大小写

只用小写。

All code has to be lowercase: This applies to HTML element names,
attributes, attribute values (unless text/CDATA), CSS selectors, properties, and
property values (with the exception of strings).

<!-- Not recommended -->
<A HREF="/">Home</A>

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

/* Not recommended */
color: #E5E5E5;

/* Recommended */
color: #e5e5e5;

结尾的空白

去掉结尾的空白。

Trailing white spaces are unnecessary and can complicate
diffs.

<!-- Not recommended -->
<p>What?_

<!-- Recommended -->
<p>Yes please.

通用元标记代码规则

编码

使用 UTF-8 (no BOM).

Make sure your editor uses UTF-8 as character encoding,
without a byte order mark.

Specify the encoding in HTML templates and documents via <meta charset="utf-8">. Do not specify
the encoding of style sheets as these assume UTF-8.

(More on encodings and when and how to specify them can be
found in Handling
character encodings in HTML and CSS.)

注释

按需注释，尽量注释。

Use comments to explain code: What does it cover, what
purpose does it serve, why is respective solution used or
preferred?

(This item is optional as it is not deemed a realistic
expectation to always demand fully documented code. Mileage
may vary heavily for HTML and CSS code and depends on the
project’s complexity.)

待处理任务(TODO)

使用TODO声明待处理任务。

Highlight todos by using the keyword TODO only,
not other common formats like @@.

Append a contact (username or mailing list) in parentheses
as with the format TODO(contact).

Append action items after a colon as in TODO: action item.

{# TODO(john.doe): revisit centering #}
<center>Test</center>

<!-- TODO: remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

HTML代码格式规则

文档类型

使用 HTML5。

HTML5 (HTML syntax) is preferred for all HTML documents: <!DOCTYPE html>.

(It’s recommended to use HTML, as text/html. Do not use
XHTML. XHTML, as application/xhtml+xml,
lacks both browser and infrastructure support and offers
less room for optimization than HTML.)

Although fine with HTML, do not close void elements, i.e. write <br>, not <br />.

HTML语法校验

尽量使用规范的html标记。

Use valid HTML code unless that is not possible due to
otherwise unattainable performance goals regarding file size.

Use tools such as the W3C
HTML validator to test.

Using valid HTML is a measurable baseline quality attribute
that contributes to learning about technical requirements
and constraints, and that ensures proper HTML usage.

<!-- Not recommended -->
<title>Test</title>
<article>This is only a test.

<!-- Recommended -->
<!DOCTYPE html>
<meta charset="utf-8">
<title>Test</title>
<article>This is only a test.</article>

语义

按HTML标记的语义使用它们。

Use elements (sometimes incorrectly called “tags”) for what
they have been created for. For example, use heading
elements for headings, p elements for
paragraphs, a elements for anchors, etc.

Using HTML according to its purpose is important for
accessibility, reuse, and code efficiency reasons.

<!-- Not recommended -->
<div onclick="goToRecommendations();">All recommendations</div>

<!-- Recommended -->
<a href="recommendations/">All recommendations</a>

多媒体内容的补救措施

为多媒体内容预留可替换的补救内容

For multimedia, such as images, videos, animated objects via canvas, make sure to offer alternative
access. For images that means use of meaningful alternative
text (alt) and for video and audio transcripts
and captions, if available.

Providing alternative contents is important for
accessibility reasons: A blind user has few cues to tell
what an image is about without @alt, and other
users may have no way of understanding what video or audio
contents are about either.

(For images whose alt attributes would
introduce redundancy, and for images whose purpose is purely
decorative which you cannot immediately use CSS for, use no
alternative text, as in alt="".)

<!-- Not recommended -->
<img src="spreadsheet.png">

<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

不相干内容分离

按表现内容分离代码。

Strictly keep structure (markup), presentation (styling),
and behavior (scripting) apart, and try to keep the
interaction between the three to an absolute minimum.

That is, make sure documents and templates contain only HTML
and HTML that is solely serving structural purposes. Move
everything presentational into style sheets, and everything
behavioral into scripts.

In addition, keep the contact area as small as possible by
linking as few style sheets and scripts as possible from
documents and templates.

Separating structure from presentation from behavior is
important for maintenance reasons. It is always more
expensive to change HTML documents and templates than it is
to update style sheets and scripts.

<!-- Not recommended -->
<!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>

<!-- Recommended -->
<!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!

特殊字符

不要使用转义代码

There is no need to use entity references like —, ”, or ☺, assuming the same encoding
(UTF-8) is used for files and editors as well as among
teams.

The only exceptions apply to characters with special meaning
in HTML (like < and &) as
well as control or “invisible” characters (like no-break
spaces).

<!-- Not recommended -->
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.

<!-- Recommended -->
The currency symbol for the Euro is “€”.

可选标记

忽略可选标记(optional).

For file size optimization and scannability purposes,
consider omitting optional tags.
The HTML5
specification defines what tags can be omitted.

(This approach may require a grace period to be established
as a wider guideline as it’s significantly different
from what web developers are typically taught. For
consistency and simplicity reasons it’s best served
omitting all optional tags, not just a selection.)

<!-- Not recommended -->
<!DOCTYPE html>
<html>
  <head>
    <title>Spending money, spending bytes</title>
  </head>
  <body>
    <p>Sic.</p>
  </body>
</html>

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

type属性

省去style sheets和scripts上的type属性。

Do not use type attributes for style sheets
(unless not using CSS) and scripts (unless not using
JavaScript).

Specifying type attributes in these contexts is
not necessary as HTML5 implies text/css and text/javascript as defaults. This can be safely done even for older browsers.

<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
  type="text/css">

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

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

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

HTML代码格式化规则

通用格式化规则

每个代码块，list, table元素都另起新行，缩进它们的子元素。

Independent of the styling of an element (as CSS allows
elements to assume a different role per display property), put every block, list, or table element on a new
line.

Also, indent them if they are child elements of a block,
list, or table element.

(If you run into issues around whitespace between list items
it’s acceptable to put all li elements in one
line. 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>

HTML里的引号

在括引属性值时用双引号。

Use double ("") rather than single quotation marks
('') around attribute values.

<!-- Not recommended -->
<a class='maia-button maia-button-secondary'>Sign in</a>

<!-- Recommended -->
<a class="maia-button maia-button-secondary">Sign in</a>

CSS代码格式规则

CSS语法校验

使用规范的CSS代码。

Unless dealing with CSS validator bugs or requiring
proprietary syntax, use valid CSS code.

Use tools such as the W3C
CSS validator to test.

Using valid CSS is a measurable baseline quality attribute
that allows to spot CSS code that may not have any effect
and can be removed, and that ensures proper CSS usage.

ID和Class命名

使用有意义或通用的ID和class名。

Instead of presentational or cryptic names, always use ID
and class names that reflect the purpose of the element in
question, or that are otherwise generic.

Names that are specific and reflect the purpose of the
element should be preferred as these are most understandable
and the least likely to change.

Generic names are simply a fallback for elements that have no
particular or no meaning different from their siblings. They are
typically needed as “helpers.”

Using functional or generic names reduces the probability of
unnecessary document or template changes.

/* Not recommended: meaningless */
#yee-1901 {}

/* Not recommended: presentational */
.button-green {}
.clear {}

/* Recommended: specific */
#gallery {}
#login {}
.video {}

/* Recommended: generic */
.aux {}
.alt {}

ID和Class名称的格式

尽量简短。

Try to convey what an ID or class is about while being as
brief as possible.

Using ID and class names this way contributes to acceptable
levels of understandability and code efficiency.

/* Not recommended */
#navigation {}
.atr {}

/* Recommended */
#nav {}
.author {}

Type选择器

避免在ID和class名称前指定type类型选择器。

Unless necessary (for example with helper classes), do not
use element names in conjunction with IDs or classes.

Avoiding unnecessary ancestor selectors is useful for performance
reasons.

/* Not recommended */
ul#example {}
div.error {}

/* Recommended */
#example {}
.error {}

属性简写

尽量使用属性简写。

CSS offers a variety of shorthand properties (like font)
that should be used whenever possible, even in cases where
only one value is explicitly set.

Using shorthand properties is useful for code efficiency and
understandability.

/* Not recommended */
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;

/* Recommended */
border-top: 0;
font: 100%/1.6 palatino, georgia, serif;
padding: 0 1em 2em;

0的单位

省去0的单位。

Do not use units after 0 values unless they are
required.

margin: 0;
padding: 0;

开头的0

省去数值中开头的0。

Do not use put 0s in front of values or lengths
between -1 and 1.

font-size: .8em;

十六进制写法

尽量使用3个字符表示十六进制数值。

For color values that permit it, 3 character hexadecimal
notation is shorter and more succinct.

/* Not recommended */
color: #eebbcc;

/* Recommended */
color: #ebc;

前缀

给选择器命名时可以针对特定的应用加上易于区分的前缀。(optional)

In large projects as well as for code that gets embedded in
other projects or on external sites use prefixes (as
namespaces) for ID and class names. Use short, unique
identifiers followed by a dash.

Using namespaces helps preventing naming conflicts and can
make maintenance easier, for example in search and replace
operations.

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

ID和Class名称里的间隔符

使用中横线分隔ID和class名称里的单词。

Do not concatenate words and abbreviations in selectors by
any characters (including none at all) other than hyphens,
in order to improve understanding and scannability.

/* Not recommended: does not separate the words “demo” and “image” */
.demoimage {}

/* Not recommended: uses underscore instead of hyphen */
.error_status {}

/* Recommended */
#video-id {}
.ads-sample {}

Hacks

Avoid user agent detection as well as CSS “hacks”—try a different
approach first.

It’s tempting to address styling differences over user
agent detection or special CSS filters, workarounds, and
hacks. Both approaches should be considered last resort in
order to achieve and maintain an efficient and manageable
code base. Put another way, giving detection and hacks a
free pass will hurt projects in the long run as projects
tend to take the way of least resistance. That is, allowing
and making it easy to use detection and hacks means using
detection and hacks more frequently—and more frequently
is too frequently.

CSS代码格式化规则

声明的顺序

按字母顺序声明代码。

Put declarations in alphabetical order in order to achieve
consistent code in a way that is easy to remember and
maintain.

Ignore vendor-specific prefixes for sorting purposes. However,
multiple vendor-specific prefixes for a certain CSS property should
be kept sorted (e.g. -moz prefix comes before -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;

代码块的缩进

所有的代码块都要缩进。

Indent all block
content, that is rules within rules as well as declarations, so to
reflect hierarchy and improve understanding.

@media screen, projection {

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

}

声明的结尾出

在每个声明后面加上一个分号。

End every declaration with a semicolon for consistency and
extensibility reasons.

/* Not recommended */
.test {
  display: block;
  height: 100px
}

/* Recommended */
.test {
  display: block;
  height: 100px;
}

属性名的结尾处

在属性后的冒号后面留一个空格。

Always use a single space between property and value (but no
space between property and colon) for consistency reasons.

/* Not recommended */
h3 {
  font-weight:bold;
}

/* Recommended */
h3 {
  font-weight: bold;
}

选择器和代码块的分隔

在最后一个选择器和代码块之间留一个空格。

Always use a single space between the last selector and the opening
brace that begins the declaration
block.

The opening brace should be on the same line as the last selector in a
given rule.

/* Not recommended: missing space */
#video{
  margin-top: 1em;
}

/* Not recommended: unnecessary line break */
#video
{
  margin-top: 1em;
}

/* Recommended */
#video {
  margin-top: 1em;
}

选择器声明的分隔

声明每个选择器时都用一个新行。

Always start a new line for each selector and declaration.

/* Not recommended */
a:focus, a:active {
  position: relative; top: 1px;
}

/* Recommended */
h1,
h2,
h3 {
  font-weight: normal;
  line-height: 1.2;
}

规则的分隔

用新行分隔每个规则。

Always put a blank line (two line breaks) between rules.

html {
  background: #fff;
}

body {
  margin: auto;
  width: 50%;
}

CSS里的引号

在属性值和属性选择器里使用单引号。

Use single ('') rather than double ("")
quotation marks for attribute selectors or property values. Do not
use quotation marks in URI values (url()).

Exception: If you do need to use the @charset rule,
use double quotation marks—single
quotation marks are not permitted.

/* Not recommended */
@import url("//www.google.com/css/maia.css");

html {
  font-family: "open sans", arial, sans-serif;
}

/* Recommended */
@import url(//www.google.com/css/maia.css);

html {
  font-family: 'open sans', arial, sans-serif;
}

CSS元标记代码规则

分开注释

按段落内容分开注释(optional).

If possible, group style sheet sections together by using
comments. Separate sections with new lines.

/* Header */

#adw-header {}

/* Footer */

#adw-footer {}

/* Gallery */

.adw-gallery {}

结束语

保持一致的格式。

If you’re editing code, take a few minutes to look at the code
around you and determine its style. If they use spaces around
all their arithmetic operators, you should too. If their
comments have little boxes of hash marks around them, make your
comments have little boxes of hash marks around them too.

The point of having style guidelines is to have a common vocabulary
of coding so people can concentrate on what you’re saying rather
than on how you’re saying it. We present global style rules here so
people know the vocabulary, but local style is also important. If
code you add to a file looks drastically different from the existing
code around it, it throws readers out of their rhythm when they go to
read it. Avoid this.

版本 2.23

阅读余下内容

标签：