Overview
This document defines the writing format and style rules for HTML/CSS. It aims to improve collaboration and code quality, and to support the underlying infrastructure. It applies to HTML/CSS files, including GSS files. As long as code quality is maintainable, it can be well obfuscated, compressed, and merged by tools.
Style Rules
Protocol
Omit the protocol header when writing embedded resources
- Omit the protocol header declarations (http:, https:) in URLs for images, media files, stylesheets, and scripts. If the URL does not use these two declarations, do not omit them.
- Omitting the protocol declaration makes URLs relative, preventing content confusion issues and avoiding redundant downloads of small files.
<!-- 不推荐 -->
<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);
}
Formatting Rules
Indentation
Indent by two spaces at a time.
Capitalization
Use lowercase letters only.
Trailing Whitespace
Remove trailing white space.
Metadata Rules
Encoding
Use UTF-8 encoding without a BOM header.
Have your editor write in UTF-8 encoding format without a byte order mark.
Specify the encoding in HTML templates and files with <meta charset="utf-8">. There is no need to specify the encoding for stylesheets; it defaults to UTF-8.
(For more information about encoding and how to specify it, seeCharacter Sets & Encodings in XHTML, HTML and CSS。）
Comments
Explain the code you write as much as possible.
Use comments to explain code: what it includes, what its purpose is, what it can do, why use this solution, or is it just because of preference?
(This rule is optional; it is not necessary to describe every piece of code in full detail, as it will add weight to HTML and CSS code. It depends on the complexity of the project.)
Action Items
Use TODO to mark to-dos and active action items.
Use only TODO to highlight pending items; do not use other common formats, such as @@.
Append a contact (username or email list) in parentheses, e.g., TODO(contact).
You can append action item descriptions after a colon, e.g., TODO: action item description.
{# TODO(cha.jn): 重新置中 #}
<center>Test</center>
<!-- TODO: 删除可选元素 -->
<ul>
<li>Apples</li>
<li>Oranges</li>
</ul>
HTML Style Rules
Document Type
Please use the HTML5 standard.
HTML Code Validity
Use valid HTML code whenever possible.
Write valid HTML code; otherwise, it is difficult to achieve performance improvements.
Use tools like thisW3C HTML validatorto test.
HTML code validity is an important quality measure and ensures that HTML code can be used correctly.
<!-- 不推荐 --> <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>
Semantics
Use HTML elements according to their purpose.
When using elements (sometimes mistakenly called "tags"), know why you are using them and whether it is correct. For example, use heading elements for headings, p elements for paragraphs, a elements for anchors, etc.
Using HTML elements according to their purpose is important; it involves issues such as document accessibility, reuse, and code efficiency.
<!-- 不推荐 --> <div onclick="goToRecommendations();">All recommendations</div> <!-- 推荐 --> <a href="recommendations/index.html">All recommendations</a>
Multimedia Fallback
Provide alternative content for multimedia.
For multimedia, such as images, videos, and animated elements loaded via canvas, ensure alternative content is provided. Use meaningful alternative text (alt) for images, and valid transcripts and captions for video and audio.
Providing alternative content is important because it gives blind users descriptive text, using @alt to tell them what the image is about, and gives hints to users who may not have understood the video or audio content.
(The alt attribute of an image can be redundant; if an image is used only for decoration that cannot be immediately achieved with CSS, there is no need for alternative text, and you can write alt="" .)
<!-- 不推荐 --> <img src="spreadsheet.png.html"> <!-- 推荐 --> <img src="spreadsheet.png.html" alt="电子表格截图">
Separation of Concerns
Separate presentation and behavior.
Strictly keep structure (markup), presentation (styles), and behavior (scripts) separated, and keep interaction among the three to a minimum.
Ensure that documents and templates contain only HTML structure; put all presentation into stylesheets and all behavior into scripts.
In addition, try to minimize the contact area of scripts and stylesheets in documents and templates, i.e., reduce external linking.
It is very important to maintain presentation and behavior separately, because changing HTML document structure and templates is more costly than updating stylesheets and scripts.
<!-- 不推荐 --> <!DOCTYPE html> <title>HTML sucks</title> <link rel="stylesheet" href="base.css.html" media="screen"> <link rel="stylesheet" href="grid.css.html" media="screen"> <link rel="stylesheet" href="print.css.html" 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.html"> <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!
Entity References
Do not use entity references.
There is no need to use entity references like —, ”, and ☺, assuming that the files and editors used by the team use the same encoding (UTF-8).
Characters with special meaning in HTML documents (such as
<
and
&
) are exceptions. Oh, and also "invisible" characters (such as no-break space).
<!-- 不推荐 --> 欧元货币符号是 “&eur;”。 <!-- 推荐 --> 欧元货币符号是 “€”。
Optional Tags
Omit optional tags (optional).
For optimizing file size and validation, you may consider omitting optional tags. For which tags are optional, refer toHTML5 specification。
(This approach may require more precise specifications to establish, and many developers have different opinions on it. For reasons of consistency and brevity, it is necessary to omit all optional tags.)
<!-- 不推荐 -->
<!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 attribute
Omit in tags for stylesheets and scripts.
type
attribute
Do not write in tags for stylesheets (unless not using CSS) and scripts (unless not using JavaScript).
type
attribute.
HTML5 defaults
type
is
text/css
and
text/javascript
type, so there is no need to specify it. Even older browsers support it.
<!-- 不推荐 --> <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 Formatting Rules
Each block element, list element, or table element occupies its own line, and each child element is indented relative to its parent element.
The style of independent elements (as CSS allows elements to assume a different role per
display
property), put block elements, list elements, or table elements on a new line.
Additionally, indent child elements of block elements, list elements, or table elements.
(If whitespace text node issues around list items occur, try putting all
li
elements on one line.)
<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>