mirror of
https://github.com/google/styleguide.git
synced 2024-03-22 13:11:43 +08:00
5684bbc8b5
- Add boost::bimap to the list of allowed Boost libraries. - C++11: remove mention of constexpr. - Remove noun/verb naming rules, and consolidate "General Naming Rules". - C++11: allow variadic templates. - Revise guidance on function definition comments. - Clarify that one space is sufficient before trailing /* */ comments. - C++11: allow alias templates. - C++11: allow <array>, deprecate Boost array. - C++11: allow unique_ptr, deprecate Boost pointer container. - C++11: allow braced initializer lists. Update Objective-C style guide to 2.56: - Add details on constant declarations to clarify naming and scope issues. - Update link to Apple's Objective-C guide. - Allow left-aligning multi-block method invocation segments. - Add section on container literals. Update Python style guide to 2.54: - Allow str.format in addition to the % operator. - Allow #!/usr/bin/python2 and #!/usr/bin/python3. - Move the closing brace example from column 4 to 0. - Remove the requirement to use named parameters for arguments with defaults. Update HTML/CSS style guide to 2.23: - No changes. Update JavaScript style guide to 2.82: - Fix typos, whitespace, and character entities. - Include property descriptions in the clause about omitting obvious comments. - Make file overviews optional. - Fix example in "HTML in JSDoc" section. - Remove the semicolon-insertion language from the operators section. - State that complete sentences are recommended but not required. - Document usage of goog.scope to declare new classes. Update Common Lisp style guide to 1.20: - Indicate both variable and function predicates require a "p". - Make the abbreviations rules consistent and in one location. - Don't allow for the use of &AUX. - Allow for "body" and "end" as exceptions to the suffix rule. - Use the TODO convention to mark code that needs to be addressed. - Remove file maintainership requirements, require a description. - Change top-level form requirements to the length of a page. - Remove "don't be clever".
1118 lines
35 KiB
XML
1118 lines
35 KiB
XML
<?xml version="1.0"?>
|
||
<?xml-stylesheet type="text/xsl" href="styleguide.xsl"?>
|
||
<GUIDE title="Google HTML/CSS Style Guide">
|
||
<p class="revision">
|
||
|
||
Revision 2.23
|
||
</p>
|
||
|
||
<OVERVIEW>
|
||
<CATEGORY title="Important Note">
|
||
<STYLEPOINT title="Displaying Hidden Details in This Guide">
|
||
<SUMMARY>
|
||
This style guide contains many details that are initially
|
||
hidden from view. They are marked by the triangle icon, which you
|
||
see here on your left. Click it now.
|
||
You should see “Hooray” appear below.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Hooray! Now you know you can expand points to get more
|
||
details. Alternatively, there’s a “toggle all” at the
|
||
top of this document.
|
||
</p>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
<CATEGORY title="Background">
|
||
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
|
||
</CATEGORY>
|
||
</OVERVIEW>
|
||
|
||
<CATEGORY title="General Style Rules">
|
||
<STYLEPOINT title="Protocol">
|
||
<SUMMARY>
|
||
Omit the protocol from embedded resources.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Omit the protocol portion (<code>http:</code>,
|
||
<code>https:</code>) from URLs pointing to images and other
|
||
media files, style sheets, and scripts unless the respective
|
||
files are not available over both protocols.
|
||
</p>
|
||
<p>
|
||
Omitting the protocol—which makes the URL
|
||
relative—prevents mixed content issues and results in
|
||
minor file size savings.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
</CODE_SNIPPET>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
.example {
|
||
background: url(http://www.google.com/images/example);
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
.example {
|
||
background: url(//www.google.com/images/example);
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="General Formatting Rules">
|
||
<STYLEPOINT title="Indentation">
|
||
<SUMMARY>
|
||
Indent by 2 spaces at a time.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Don’t use tabs or mix tabs and spaces for indentation.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
<ul>
|
||
<li>Fantastic
|
||
<li>Great
|
||
</ul>
|
||
</CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
.example {
|
||
color: blue;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Capitalization">
|
||
<SUMMARY>
|
||
Use only lowercase.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
All code has to be lowercase: This applies to HTML element names,
|
||
attributes, attribute values (unless
|
||
<code>text/CDATA</code>), CSS selectors, properties, and
|
||
property values (with the exception of strings).
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<A HREF="/">Home</A>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<img src="google.png" alt="Google">
|
||
</CODE_SNIPPET>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
color: #E5E5E5;
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
color: #e5e5e5;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Trailing Whitespace">
|
||
<SUMMARY>
|
||
Remove trailing white spaces.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Trailing white spaces are unnecessary and can complicate
|
||
diffs.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<p>What?_
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<p>Yes please.
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="General Meta Rules">
|
||
<STYLEPOINT title="Encoding">
|
||
<SUMMARY>
|
||
Use UTF-8 (no BOM).
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Make sure your editor uses UTF-8 as character encoding,
|
||
without a byte order mark.
|
||
</p>
|
||
<p>
|
||
Specify the encoding in HTML templates and documents via
|
||
<code><meta charset="utf-8"></code>. Do not specify
|
||
the encoding of style sheets as these assume UTF-8.
|
||
</p>
|
||
<p>
|
||
(More on encodings and when and how to specify them can be
|
||
found in <a href="http://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
|
||
character encodings in HTML and CSS</a>.)
|
||
</p>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Comments">
|
||
<SUMMARY>
|
||
Explain code as needed, where possible.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Use comments to explain code: What does it cover, what
|
||
purpose does it serve, why is respective solution used or
|
||
preferred?
|
||
</p>
|
||
<p>
|
||
(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.)
|
||
</p>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Action Items">
|
||
<SUMMARY>
|
||
Mark todos and action items with <code>TODO</code>.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Highlight todos by using the keyword <code>TODO</code> only,
|
||
not other common formats like <code>@@</code>.
|
||
</p>
|
||
<p>
|
||
Append a contact (username or mailing list) in parentheses
|
||
as with the format <code>TODO(contact)</code>.
|
||
</p>
|
||
<p>
|
||
Append action items after a colon as in <code>TODO: action
|
||
item</code>.
|
||
</p>
|
||
|
||
<CODE_SNIPPET>
|
||
{# TODO(john.doe): revisit centering #}
|
||
<center>Test</center>
|
||
</CODE_SNIPPET>
|
||
|
||
<CODE_SNIPPET>
|
||
<!-- TODO: remove optional tags -->
|
||
<ul>
|
||
<li>Apples</li>
|
||
<li>Oranges</li>
|
||
</ul>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="HTML Style Rules">
|
||
<STYLEPOINT title="Document Type">
|
||
<SUMMARY>
|
||
Use HTML5.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
HTML5 (HTML syntax) is preferred for all HTML documents:
|
||
<code><!DOCTYPE html></code>.
|
||
</p>
|
||
<p>
|
||
(It’s recommended to use HTML, as <code>text/html</code>. Do not use
|
||
XHTML. XHTML, as <a href="http://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>,
|
||
lacks both browser and infrastructure support and offers
|
||
less room for optimization than HTML.)
|
||
</p>
|
||
<p>
|
||
Although fine with HTML, do not close void elements, i.e. write
|
||
<code><br></code>, not <code><br /></code>.
|
||
</p>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="HTML Validity">
|
||
<SUMMARY>
|
||
Use valid HTML where possible.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Use valid HTML code unless that is not possible due to
|
||
otherwise unattainable performance goals regarding file size.
|
||
</p>
|
||
|
||
<p>
|
||
Use tools such as the <a href="http://validator.w3.org/nu/">W3C
|
||
HTML validator</a> to test.
|
||
</p>
|
||
<p>
|
||
Using valid HTML is a measurable baseline quality attribute
|
||
that contributes to learning about technical requirements
|
||
and constraints, and that ensures proper HTML usage.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<title>Test</title>
|
||
<article>This is only a test.
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<!DOCTYPE html>
|
||
<meta charset="utf-8">
|
||
<title>Test</title>
|
||
<article>This is only a test.</article>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Semantics">
|
||
<SUMMARY>
|
||
Use HTML according to its purpose.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Use elements (sometimes incorrectly called “tags”) for what
|
||
they have been created for. For example, use heading
|
||
elements for headings, <code>p</code> elements for
|
||
paragraphs, <code>a</code> elements for anchors, etc.
|
||
</p>
|
||
<p>
|
||
Using HTML according to its purpose is important for
|
||
accessibility, reuse, and code efficiency reasons.
|
||
</p>
|
||
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<div onclick="goToRecommendations();">All recommendations</div>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<a href="recommendations/">All recommendations</a>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Multimedia Fallback">
|
||
<SUMMARY>
|
||
Provide alternative contents for multimedia.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
For multimedia, such as images, videos, animated objects via
|
||
<code>canvas</code>, make sure to offer alternative
|
||
access. For images that means use of meaningful alternative
|
||
text (<code>alt</code>) and for video and audio transcripts
|
||
and captions, if available.
|
||
</p>
|
||
<p>
|
||
Providing alternative contents is important for
|
||
accessibility reasons: A blind user has few cues to tell
|
||
what an image is about without <code>@alt</code>, and other
|
||
users may have no way of understanding what video or audio
|
||
contents are about either.
|
||
</p>
|
||
<p>
|
||
(For images whose <code>alt</code> 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 <code>alt=""</code>.)
|
||
</p>
|
||
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<img src="spreadsheet.png">
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
|
||
<STYLEPOINT title="Separation of Concerns">
|
||
<SUMMARY>
|
||
Separate structure from presentation from behavior.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Strictly keep structure (markup), presentation (styling),
|
||
and behavior (scripting) apart, and try to keep the
|
||
interaction between the three to an absolute minimum.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
In addition, keep the contact area as small as possible by
|
||
linking as few style sheets and scripts as possible from
|
||
documents and templates.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- 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>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- 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!
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Entity References">
|
||
<SUMMARY>
|
||
Do not use entity references.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
There is no need to use entity references like
|
||
<code>&mdash;</code>, <code>&rdquo;</code>, or
|
||
<code>&#x263a;</code>, assuming the same encoding
|
||
(UTF-8) is used for files and editors as well as among
|
||
teams.
|
||
</p>
|
||
<p>
|
||
The only exceptions apply to characters with special meaning
|
||
in HTML (like <code><</code> and <code>&</code>) as
|
||
well as control or “invisible” characters (like no-break
|
||
spaces).
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
The currency symbol for the Euro is “€”.
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Optional Tags">
|
||
<SUMMARY>
|
||
Omit optional tags (optional).
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
For file size optimization and scannability purposes,
|
||
consider omitting optional tags.
|
||
The <a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5
|
||
specification</a> defines what tags can be omitted.
|
||
</p>
|
||
<p>
|
||
(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.)
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<!DOCTYPE html>
|
||
<html>
|
||
<head>
|
||
<title>Spending money, spending bytes</title>
|
||
</head>
|
||
<body>
|
||
<p>Sic.</p>
|
||
</body>
|
||
</html>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<!DOCTYPE html>
|
||
<title>Saving money, saving bytes</title>
|
||
<p>Qed.
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="type Attributes">
|
||
<SUMMARY>
|
||
Omit <code>type</code> attributes for style sheets and scripts.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Do not use <code>type</code> attributes for style sheets
|
||
(unless not using CSS) and scripts (unless not using
|
||
JavaScript).
|
||
</p>
|
||
<p>
|
||
Specifying <code>type</code> attributes in these contexts is
|
||
not necessary as HTML5 implies
|
||
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
|
||
and
|
||
<a href="http://www.whatwg.org/specs/web-apps/current-work/multipage/scripting-1.html#attr-script-type"><code>text/javascript</code></a>
|
||
as defaults. This can be safely done even for older browsers.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<link rel="stylesheet" href="//www.google.com/css/maia.css"
|
||
type="text/css">
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<link rel="stylesheet" href="//www.google.com/css/maia.css">
|
||
</CODE_SNIPPET>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<script src="//www.google.com/js/gweb/analytics/autotrack.js"
|
||
type="text/javascript"></script>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="HTML Formatting Rules">
|
||
<STYLEPOINT title="General Formatting">
|
||
<SUMMARY>
|
||
Use a new line for every block, list, or table element, and
|
||
indent every such child element.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Independent of the styling of an element (as CSS allows
|
||
elements to assume a different role per <code>display</code>
|
||
property), put every block, list, or table element on a new
|
||
line.
|
||
</p>
|
||
<p>
|
||
Also, indent them if they are child elements of a block,
|
||
list, or table element.
|
||
</p>
|
||
<p>
|
||
(If you run into issues around whitespace between list items
|
||
it’s acceptable to put all <code>li</code> elements in one
|
||
line. A linter is encouraged to throw a warning instead of
|
||
an error.)
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
<blockquote>
|
||
<p><em>Space</em>, the final frontier.</p>
|
||
</blockquote>
|
||
</CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<ul>
|
||
<li>Moe
|
||
<li>Larry
|
||
<li>Curly
|
||
</ul>
|
||
</CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<table>
|
||
<thead>
|
||
<tr>
|
||
<th scope="col">Income
|
||
<th scope="col">Taxes
|
||
<tbody>
|
||
<tr>
|
||
<td>$ 5.00
|
||
<td>$ 4.50
|
||
</table>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="HTML Quotation Marks">
|
||
<SUMMARY>
|
||
When quoting attributes values, use double quotation marks.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Use double (<code>""</code>) rather than single quotation marks
|
||
(<code>''</code>) around attribute values.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
<!-- Not recommended -->
|
||
<a class='maia-button maia-button-secondary'>Sign in</a>
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
<!-- Recommended -->
|
||
<a class="maia-button maia-button-secondary">Sign in</a>
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="CSS Style Rules">
|
||
<STYLEPOINT title="CSS Validity">
|
||
<SUMMARY>
|
||
Use valid CSS where possible.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Unless dealing with CSS validator bugs or requiring
|
||
proprietary syntax, use valid CSS code.
|
||
</p>
|
||
|
||
<p>
|
||
Use tools such as the <a href="http://jigsaw.w3.org/css-validator/">W3C
|
||
CSS validator</a> to test.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="ID and Class Naming">
|
||
<SUMMARY>
|
||
Use meaningful or generic ID and class names.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
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.”
|
||
</p>
|
||
<p>
|
||
Using functional or generic names reduces the probability of
|
||
unnecessary document or template changes.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended: meaningless */
|
||
#yee-1901 {}
|
||
|
||
/* Not recommended: presentational */
|
||
.button-green {}
|
||
.clear {}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended: specific */
|
||
#gallery {}
|
||
#login {}
|
||
.video {}
|
||
|
||
/* Recommended: generic */
|
||
.aux {}
|
||
.alt {}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="ID and Class Name Style">
|
||
<SUMMARY>
|
||
Use ID and class names that are as short as possible but as long as
|
||
necessary.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Try to convey what an ID or class is about while being as
|
||
brief as possible.
|
||
</p>
|
||
<p>
|
||
Using ID and class names this way contributes to acceptable
|
||
levels of understandability and code efficiency.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
#navigation {}
|
||
.atr {}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
#nav {}
|
||
.author {}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
|
||
<STYLEPOINT title="Type Selectors">
|
||
<SUMMARY>
|
||
Avoid qualifying ID and class names with type selectors.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>Unless necessary (for example with helper classes), do not
|
||
use element names in conjunction with IDs or classes.
|
||
</p>
|
||
<p>
|
||
Avoiding unnecessary ancestor selectors is useful for <a href="http://www.stevesouders.com/blog/2009/06/18/simplifying-css-selectors/">performance
|
||
reasons</a>.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
ul#example {}
|
||
div.error {}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
#example {}
|
||
.error {}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Shorthand Properties">
|
||
<SUMMARY>
|
||
Use shorthand properties where possible.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
CSS offers a variety of <a href="http://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
|
||
properties (like <code>font</code>)
|
||
that should be used whenever possible, even in cases where
|
||
only one value is explicitly set.
|
||
</p>
|
||
<p>
|
||
Using shorthand properties is useful for code efficiency and
|
||
understandability.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* 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;
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
border-top: 0;
|
||
font: 100%/1.6 palatino, georgia, serif;
|
||
padding: 0 1em 2em;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="0 and Units">
|
||
<SUMMARY>
|
||
Omit unit specification after “0” values.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Do not use units after <code>0</code> values unless they are
|
||
required.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
margin: 0;
|
||
padding: 0;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Leading 0s">
|
||
<SUMMARY>
|
||
Omit leading “0”s in values.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Do not use put <code>0</code>s in front of values or lengths
|
||
between -1 and 1.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
font-size: .8em;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Hexadecimal Notation">
|
||
<SUMMARY>
|
||
Use 3 character hexadecimal notation where possible.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
For color values that permit it, 3 character hexadecimal
|
||
notation is shorter and more succinct.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
color: #eebbcc;
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
color: #ebc;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Prefixes">
|
||
<SUMMARY>
|
||
Prefix selectors with an application-specific prefix (optional).
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
|
||
<p>
|
||
Using namespaces helps preventing naming conflicts and can
|
||
make maintenance easier, for example in search and replace
|
||
operations.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
.adw-help {} /* AdWords */
|
||
#maia-note {} /* Maia */
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="ID and Class Name Delimiters">
|
||
<SUMMARY>
|
||
Separate words in ID and class names by a hyphen.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended: does not separate the words “demo” and “image” */
|
||
.demoimage {}
|
||
|
||
/* Not recommended: uses underscore instead of hyphen */
|
||
.error_status {}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
#video-id {}
|
||
.ads-sample {}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Hacks">
|
||
<SUMMARY>
|
||
Avoid user agent detection as well as CSS “hacks”—try a different
|
||
approach first.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
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.
|
||
</p>
|
||
|
||
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="CSS Formatting Rules">
|
||
<STYLEPOINT title="Declaration Order">
|
||
<SUMMARY>
|
||
Alphabetize declarations.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Put declarations in alphabetical order in order to achieve
|
||
consistent code in a way that is easy to remember and
|
||
maintain.
|
||
</p>
|
||
<p>
|
||
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).
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
background: fuchsia;
|
||
border: 1px solid;
|
||
-moz-border-radius: 4px;
|
||
-webkit-border-radius: 4px;
|
||
border-radius: 4px;
|
||
color: black;
|
||
text-align: center;
|
||
text-indent: 2em;
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Block Content Indentation">
|
||
<SUMMARY>
|
||
Indent all block content.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Indent all <a href="http://www.w3.org/TR/CSS21/syndata.html#block">block
|
||
content</a>, that is rules within rules as well as declarations, so to
|
||
reflect hierarchy and improve understanding.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
@media screen, projection {
|
||
|
||
html {
|
||
background: #fff;
|
||
color: #444;
|
||
}
|
||
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Declaration Stops">
|
||
<SUMMARY>
|
||
Use a semicolon after every declaration.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
End every declaration with a semicolon for consistency and
|
||
extensibility reasons.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
.test {
|
||
display: block;
|
||
height: 100px
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
.test {
|
||
display: block;
|
||
height: 100px;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Property Name Stops">
|
||
<SUMMARY>
|
||
Use a space after a property name’s colon.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Always use a single space between property and value (but no
|
||
space between property and colon) for consistency reasons.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
h3 {
|
||
font-weight:bold;
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
h3 {
|
||
font-weight: bold;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Declaration Block Separation">
|
||
<SUMMARY>
|
||
Use a space between the last selector and the declaration block.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Always use a single space between the last selector and the opening
|
||
brace that begins the <a href="http://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration
|
||
block</a>.
|
||
</p>
|
||
<p>
|
||
The opening brace should be on the same line as the last selector in a
|
||
given rule.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended: missing space */
|
||
#video{
|
||
margin-top: 1em;
|
||
}
|
||
|
||
/* Not recommended: unnecessary line break */
|
||
#video
|
||
{
|
||
margin-top: 1em;
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
#video {
|
||
margin-top: 1em;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Selector and Declaration Separation">
|
||
<SUMMARY>
|
||
Separate selectors and declarations by new lines.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Always start a new line for each selector and declaration.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
a:focus, a:active {
|
||
position: relative; top: 1px;
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
h1,
|
||
h2,
|
||
h3 {
|
||
font-weight: normal;
|
||
line-height: 1.2;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="Rule Separation">
|
||
<SUMMARY>
|
||
Separate rules by new lines.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Always put a blank line (two line breaks) between rules.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
html {
|
||
background: #fff;
|
||
}
|
||
|
||
body {
|
||
margin: auto;
|
||
width: 50%;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
<STYLEPOINT title="CSS Quotation Marks">
|
||
<SUMMARY>
|
||
Use single quotation marks for attribute selectors and property values.
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
Use single (<code>''</code>) rather than double (<code>""</code>)
|
||
quotation marks for attribute selectors or property values. Do not
|
||
use quotation marks in URI values (<code>url()</code>).
|
||
</p>
|
||
<p>
|
||
Exception: If you do need to use the <code>@charset</code> rule,
|
||
use double quotation marks—<a href="http://www.w3.org/TR/CSS21/syndata.html#charset">single
|
||
quotation marks are not permitted</a>.
|
||
</p>
|
||
<BAD_CODE_SNIPPET>
|
||
/* Not recommended */
|
||
@import url("//www.google.com/css/maia.css");
|
||
|
||
html {
|
||
font-family: "open sans", arial, sans-serif;
|
||
}
|
||
</BAD_CODE_SNIPPET>
|
||
<CODE_SNIPPET>
|
||
/* Recommended */
|
||
@import url(//www.google.com/css/maia.css);
|
||
|
||
html {
|
||
font-family: 'open sans', arial, sans-serif;
|
||
}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
<CATEGORY title="CSS Meta Rules">
|
||
|
||
<STYLEPOINT title="Section Comments">
|
||
<SUMMARY>
|
||
Group sections by a section comment (optional).
|
||
</SUMMARY>
|
||
<BODY>
|
||
<p>
|
||
If possible, group style sheet sections together by using
|
||
comments. Separate sections with new lines.
|
||
</p>
|
||
<CODE_SNIPPET>
|
||
/* Header */
|
||
|
||
#adw-header {}
|
||
|
||
/* Footer */
|
||
|
||
#adw-footer {}
|
||
|
||
/* Gallery */
|
||
|
||
.adw-gallery {}
|
||
</CODE_SNIPPET>
|
||
</BODY>
|
||
</STYLEPOINT>
|
||
</CATEGORY>
|
||
|
||
|
||
|
||
<PARTING_WORDS>
|
||
<p>
|
||
<em>Be consistent.</em>
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
<p>
|
||
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.
|
||
</p>
|
||
</PARTING_WORDS>
|
||
|
||
<p align="right">
|
||
Revision 2.23
|
||
</p>
|
||
|
||
</GUIDE>
|