Blame - htmlcssguide.html - platform/external/google-styleguide

blob: 6fc7b39e72af049751bdd62f8ac97b475d199d4e [file] [log] [blame]

Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	1	<!DOCTYPE html>
Tony Ruscoe	ad6dee8	2017-02-27 08:16:24 +0000	[diff] [blame]	2	<html lang="en">
Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	3	<head>
Tony Ruscoe	ad6dee8	2017-02-27 08:16:24 +0000	[diff] [blame]	4	<meta charset="utf-8">
Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	5	<title>Google HTML/CSS Style Guide</title>
Tony Ruscoe	ad6dee8	2017-02-27 08:16:24 +0000	[diff] [blame]	6	<link rel="stylesheet" href="javaguide.css">
				7	<script src="include/styleguide.js"></script>
				8	<link rel="shortcut icon" href="https://www.google.com/favicon.ico">
Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	9	<script src="include/jsguide.js"></script>
				10	</head>
				11	<body onload="initStyleGuide();">
				12	<div id="content">
				13	<h1>Google HTML/CSS Style Guide</h1>
				14	<h2 id="Background">1 Background</h2>
				15
				16	<p></p>
				17
				18	<p>This document defines formatting and style rules for HTML and CSS. It aims at
				19	improving collaboration, code quality, and enabling supporting infrastructure.
				20	It applies to raw, working files that use HTML and CSS, including GSS files.
				21	Tools are free to obfuscate, minify, and compile as long as the general code
				22	quality is maintained.</p>
				23
				24	<p></p>
				25
				26	<p></p>
				27
				28	<h2 id="General">2 General</h2>
				29
				30	<h3 id="General_Style_Rules">2.1 General Style Rules</h3>
				31
				32	<h4 id="Protocol">2.1.1 Protocol</h4>
				33
				34	<p>Use the HTTPS protocol for embedded resources where possible.</p>
				35
				36	<p>Always use the HTTPS protocol (<code>https:</code>) for images and other media
				37	files, style sheets, and scripts, unless the respective files are not available
				38	over HTTPS.</p>
				39
				40	<pre><code class="language-html prettyprint badcode"><!-- Not recommended: omits the protocol -->
				41	<script src="//ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
				42
				43	<!-- Not recommended: uses the HTTP protocol -->
				44	<script src="http://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
				45	</code></pre>
				46
				47	<pre><code class="language-html prettyprint"><!-- Recommended -->
				48	<script src="https://ajax.googleapis.com/ajax/libs/jquery/3.1.0/jquery.min.js"></script>
				49	</code></pre>
				50
				51	<pre><code class="language-css prettyprint badcode">/* Not recommended: omits the protocol */
				52	@import '//fonts.googleapis.com/css?family=Open+Sans';
				53
				54	/* Not recommended: uses the HTTP protocol */
				55	@import 'http://fonts.googleapis.com/css?family=Open+Sans';
				56	</code></pre>
				57
				58	<pre><code class="language-css prettyprint">/* Recommended */
				59	@import 'https://fonts.googleapis.com/css?family=Open+Sans';
				60	</code></pre>
				61
				62
				63
				64	<p></p>
				65
				66	<p></p>
				67
				68	<p></p>
				69
				70	<h3 id="General_Formatting_Rules">2.2 General Formatting Rules</h3>
				71
				72	<h4 id="Indentation">2.2.1 Indentation</h4>
				73
				74	<p>Indent by 2 spaces at a time.</p>
				75
				76	<p>Don’t use tabs or mix tabs and spaces for indentation.</p>
				77
				78	<pre><code class="language-html prettyprint"><ul>
				79	<li>Fantastic
				80	<li>Great
				81	</ul>
				82	</code></pre>
				83
				84	<pre><code class="language-css prettyprint">.example {
				85	color: blue;
				86	}
				87	</code></pre>
				88
				89	<h4 id="Capitalization">2.2.2 Capitalization</h4>
				90
				91	<p>Use only lowercase.</p>
				92
				93	<p>All code has to be lowercase: This applies to HTML element names, attributes,
				94	attribute values (unless <code>text/CDATA</code>), CSS selectors, properties, and property
				95	values (with the exception of strings).</p>
				96
				97	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				98	<A HREF="/">Home</A>
				99	</code></pre>
				100
				101	<pre><code class="language-html prettyprint"><!-- Recommended -->
				102	<img src="google.png" alt="Google">
				103	</code></pre>
				104
				105	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				106	color: #E5E5E5;
				107	</code></pre>
				108
				109	<pre><code class="language-css prettyprint">/* Recommended */
				110	color: #e5e5e5;
				111	</code></pre>
				112
				113	<h4 id="Trailing_Whitespace">2.2.3 Trailing Whitespace</h4>
				114
				115	<p>Remove trailing white spaces.</p>
				116
				117	<p>Trailing white spaces are unnecessary and can complicate diffs.</p>
				118
				119	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				120	<p>What?_
				121	</code></pre>
				122
				123	<pre><code class="language-html prettyprint"><!-- Recommended -->
				124	<p>Yes please.
				125	</code></pre>
				126
				127	<h3 id="General_Meta_Rules">2.3 General Meta Rules</h3>
				128
				129	<h4 id="Encoding">2.3.1 Encoding</h4>
				130
				131	<p>Use UTF-8 (no BOM).</p>
				132
				133	<p>Make sure your editor uses UTF-8 as character encoding, without a byte order
				134	mark.</p>
				135
				136	<p>Specify the encoding in HTML templates and documents via <code><meta
				137	charset="utf-8"></code>. Do not specify the encoding of style sheets as these assume
				138	UTF-8.</p>
				139
				140	<p>(More on encodings and when and how to specify them can be found in <a href="https://www.w3.org/International/tutorials/tutorial-char-enc/">Handling
				141	character encodings in HTML and CSS</a>.)</p>
				142
				143	<h4 id="Comments">2.3.2 Comments</h4>
				144
				145	<p>Explain code as needed, where possible.</p>
				146
				147	<p>Use comments to explain code: What does it cover, what purpose does it serve,
				148	why is respective solution used or preferred?</p>
				149
				150	<p>(This item is optional as it is not deemed a realistic expectation to always
				151	demand fully documented code. Mileage may vary heavily for HTML and CSS code and
				152	depends on the project’s complexity.)</p>
				153
				154	<h4 id="Action_Items">2.3.3 Action Items</h4>
				155
				156	<p>Mark todos and action items with <code>TODO</code>.</p>
				157
				158	<p>Highlight todos by using the keyword <code>TODO</code> only, not other common formats like
				159	<code>@@</code>.</p>
				160
				161	<p>Append a contact (username or mailing list) in parentheses as with the format
				162	<code>TODO(contact)</code>.</p>
				163
				164	<p>Append action items after a colon as in <code>TODO: action item</code>.</p>
				165
				166	<pre></pre>
				167
				168	<pre><code class="language-django prettyprint external">{# TODO(john.doe): revisit centering #}
				169	<center>Test</center>
				170	</code></pre>
				171
				172	<p></p>
				173
				174	<pre><code class="language-html prettyprint"><!-- TODO: remove optional tags -->
				175	<ul>
				176	<li>Apples</li>
				177	<li>Oranges</li>
				178	</ul>
				179	</code></pre>
				180
				181	<h2 id="HTML">3 HTML</h2>
				182
				183	<h3 id="HTML_Style_Rules">3.1 HTML Style Rules</h3>
				184
				185	<h4 id="Document_Type">3.1.1 Document Type</h4>
				186
				187	<p>Use HTML5.</p>
				188
				189	<p>HTML5 (HTML syntax) is preferred for all HTML documents: <code><!DOCTYPE html></code>.</p>
				190
				191	<p>(It’s recommended to use HTML, as <code>text/html</code>. Do not use XHTML. XHTML, as
				192	<a href="https://hixie.ch/advocacy/xhtml"><code>application/xhtml+xml</code></a>, lacks both browser
				193	and infrastructure support and offers less room for optimization than HTML.)</p>
				194
				195	<p>Although fine with HTML, do not close void elements, i.e. write <code><br></code>, not
				196	<code><br /></code>.</p>
				197
				198	<h4 id="HTML_Validity">3.1.2 HTML Validity</h4>
				199
				200	<p>Use valid HTML where possible.</p>
				201
				202	<p>Use valid HTML code unless that is not possible due to otherwise unattainable
				203	performance goals regarding file size.</p>
				204
				205	<p>
				206
				207	Use tools such as the <a href="https://validator.w3.org/nu/">W3C HTML validator</a>
				208	to test.
				209	</p>
				210
				211	<p>Using valid HTML is a measurable baseline quality attribute that contributes to
				212	learning about technical requirements and constraints, and that ensures proper
				213	HTML usage.</p>
				214
				215	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				216	<title>Test</title>
				217	<article>This is only a test.
				218	</code></pre>
				219
				220	<pre><code class="language-html prettyprint"><!-- Recommended -->
				221	<!DOCTYPE html>
				222	<meta charset="utf-8">
				223	<title>Test</title>
				224	<article>This is only a test.</article>
				225	</code></pre>
				226
				227	<h4 id="Semantics">3.1.3 Semantics</h4>
				228
				229	<p>Use HTML according to its purpose.</p>
				230
				231	<p>Use elements (sometimes incorrectly called “tags”) for what they have been
				232	created for. For example, use heading elements for headings, <code>p</code> elements for
				233	paragraphs, <code>a</code> elements for anchors, etc.</p>
				234
				235	<p>Using HTML according to its purpose is important for accessibility, reuse, and
				236	code efficiency reasons.</p>
				237
				238	<p></p>
				239
				240	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				241	<div onclick="goToRecommendations();">All recommendations</div>
				242	</code></pre>
				243
				244	<pre><code class="language-html prettyprint"><!-- Recommended -->
				245	<a href="recommendations/">All recommendations</a>
				246	</code></pre>
				247
				248	<h4 id="Multimedia_Fallback">3.1.4 Multimedia Fallback</h4>
				249
				250	<p>Provide alternative contents for multimedia.</p>
				251
				252	<p>For multimedia, such as images, videos, animated objects via <code>canvas</code>, make sure
				253	to offer alternative access. For images that means use of meaningful alternative
				254	text (<code>alt</code>) and for video and audio transcripts and captions, if available.</p>
				255
				256	<p>Providing alternative contents is important for accessibility reasons: A blind
				257	user has few cues to tell what an image is about without <code>@alt</code>, and other users
				258	may have no way of understanding what video or audio contents are about either.</p>
				259
				260	<p>(For images whose <code>alt</code> attributes would introduce redundancy, and for images
				261	whose purpose is purely decorative which you cannot immediately use CSS for, use
				262	no alternative text, as in <code>alt=""</code>.)</p>
				263
				264	<p></p>
				265
				266	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				267	<img src="spreadsheet.png">
				268	</code></pre>
				269
				270	<pre><code class="language-html prettyprint"><!-- Recommended -->
				271	<img src="spreadsheet.png" alt="Spreadsheet screenshot.">
				272	</code></pre>
				273
				274	<h4 id="Separation_of_Concerns">3.1.5 Separation of Concerns</h4>
				275
				276	<p>Separate structure from presentation from behavior.</p>
				277
				278	<p>Strictly keep structure (markup), presentation (styling), and behavior
				279	(scripting) apart, and try to keep the interaction between the three to an
				280	absolute minimum.</p>
				281
				282	<p>That is, make sure documents and templates contain only HTML and HTML that is
				283	solely serving structural purposes. Move everything presentational into style
				284	sheets, and everything behavioral into scripts.</p>
				285
				286	<p>In addition, keep the contact area as small as possible by linking as few style
				287	sheets and scripts as possible from documents and templates.</p>
				288
				289	<p>Separating structure from presentation from behavior is important for
				290	maintenance reasons. It is always more expensive to change HTML documents and
				291	templates than it is to update style sheets and scripts.</p>
				292
				293	<p></p>
				294
				295	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				296	<!DOCTYPE html>
				297	<title>HTML sucks</title>
				298	<link rel="stylesheet" href="base.css" media="screen">
				299	<link rel="stylesheet" href="grid.css" media="screen">
				300	<link rel="stylesheet" href="print.css" media="print">
				301	<h1 style="font-size: 1em;">HTML sucks</h1>
				302	<p>I’ve read about this on a few sites but now I’m sure:
				303	<u>HTML is stupid!!1</u>
				304	<center>I can’t believe there’s no way to control the styling of
				305	my website without doing everything all over again!</center>
				306	</code></pre>
				307
				308	<pre><code class="language-html prettyprint"><!-- Recommended -->
				309	<!DOCTYPE html>
				310	<title>My first CSS-only redesign</title>
				311	<link rel="stylesheet" href="default.css">
				312	<h1>My first CSS-only redesign</h1>
				313	<p>I’ve read about this on a few sites but today I’m actually
				314	doing it: separating concerns and avoiding anything in the HTML of
				315	my website that is presentational.
				316	<p>It’s awesome!
				317	</code></pre>
				318
				319	<h4 id="Entity_References">3.1.6 Entity References</h4>
				320
				321	<p>Do not use entity references.</p>
				322
				323	<p>There is no need to use entity references like <code>&mdash;</code>, <code>&rdquo;</code>, or
				324	<code>&#x263a;</code>, assuming the same encoding (UTF-8) is used for files and editors
				325	as well as among teams.</p>
				326
				327	<p>The only exceptions apply to characters with special meaning in HTML (like <code><</code>
				328	and <code>&</code>) as well as control or “invisible” characters (like no-break spaces).</p>
				329
				330	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				331	The currency symbol for the Euro is &ldquo;&eur;&rdquo;.
				332	</code></pre>
				333
				334	<pre><code class="language-html prettyprint"><!-- Recommended -->
				335	The currency symbol for the Euro is “€”.
				336	</code></pre>
				337
				338	<h4 id="Optional_Tags">3.1.7 Optional Tags</h4>
				339
				340	<p>Omit optional tags (optional).</p>
				341
				342	<p>For file size optimization and scannability purposes, consider omitting optional
				343	tags. The <a href="https://whatwg.org/specs/web-apps/current-work/multipage/syntax.html#syntax-tag-omission">HTML5 specification</a>
				344	defines what tags can be omitted.</p>
				345
				346	<p>(This approach may require a grace period to be established as a wider guideline
				347	as it’s significantly different from what web developers are typically taught.
				348	For consistency and simplicity reasons it’s best served omitting all optional
				349	tags, not just a selection.)</p>
				350
				351	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				352	<!DOCTYPE html>
				353	<html>
				354	<head>
				355	<title>Spending money, spending bytes</title>
				356	</head>
				357	<body>
				358	<p>Sic.</p>
				359	</body>
				360	</html>
				361	</code></pre>
				362
				363	<pre><code class="language-html prettyprint"><!-- Recommended -->
				364	<!DOCTYPE html>
				365	<title>Saving money, saving bytes</title>
				366	<p>Qed.
				367	</code></pre>
				368
				369	<h4 id="type_Attributes">3.1.8 <code>type</code> Attributes</h4>
				370
				371	<p>Omit <code>type</code> attributes for style sheets and scripts.</p>
				372
				373	<p>Do not use <code>type</code> attributes for style sheets (unless not using CSS) and scripts
				374	(unless not using JavaScript).</p>
				375
				376	<p>Specifying <code>type</code> attributes in these contexts is not necessary as HTML5 implies
				377	<a href="https://whatwg.org/specs/web-apps/current-work/multipage/semantics.html#attr-style-type"><code>text/css</code></a>
				378	and <a href="https://whatwg.org/specs/web-apps/current-work/multipage/scripting.html#attr-script-type"><code>text/javascript</code></a>
				379	as defaults. This can be safely done even for older browsers.</p>
				380
				381	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				382	<link rel="stylesheet" href="https://www.google.com/css/maia.css"
				383	type="text/css">
				384	</code></pre>
				385
				386	<pre><code class="language-html prettyprint"><!-- Recommended -->
				387	<link rel="stylesheet" href="https://www.google.com/css/maia.css">
				388	</code></pre>
				389
				390	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				391	<script src="https://www.google.com/js/gweb/analytics/autotrack.js"
				392	type="text/javascript"></script>
				393	</code></pre>
				394
				395	<pre><code class="language-html prettyprint"><!-- Recommended -->
				396	<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
				397	</code></pre>
				398
				399	<h3 id="HTML_Formatting_Rules">3.2 HTML Formatting Rules</h3>
				400
				401	<h4 id="General_Formatting">3.2.1 General Formatting</h4>
				402
				403	<p>Use a new line for every block, list, or table element, and indent every such
				404	child element.</p>
				405
				406	<p>Independent of the styling of an element (as CSS allows elements to assume a
				407	different role per <code>display</code> property), put every block, list, or table element
				408	on a new line.</p>
				409
				410	<p>Also, indent them if they are child elements of a block, list, or table element.</p>
				411
				412	<p>(If you run into issues around whitespace between list items it’s acceptable to
				413	put all <code>li</code> elements in one line. A linter is encouraged to throw a warning
				414	instead of an error.)</p>
				415
				416	<pre><code class="language-html prettyprint"><blockquote>
				417	<p><em>Space</em>, the final frontier.</p>
				418	</blockquote>
				419	</code></pre>
				420
				421	<pre><code class="language-html prettyprint"><ul>
				422	<li>Moe
				423	<li>Larry
				424	<li>Curly
				425	</ul>
				426	</code></pre>
				427
				428	<pre><code class="language-html prettyprint"><table>
				429	<thead>
				430	<tr>
				431	<th scope="col">Income
				432	<th scope="col">Taxes
				433	<tbody>
				434	<tr>
				435	<td>$ 5.00
				436	<td>$ 4.50
				437	</table>
				438	</code></pre>
				439
				440	<h4 id="HTML_Quotation_Marks">3.2.2 HTML Quotation Marks</h4>
				441
				442	<p>When quoting attributes values, use double quotation marks.</p>
				443
				444	<p>Use double (<code>""</code>) rather than single quotation marks (<code>''</code>) around attribute
				445	values.</p>
				446
				447	<pre><code class="language-html prettyprint badcode"><!-- Not recommended -->
				448	<a class='maia-button maia-button-secondary'>Sign in</a>
				449	</code></pre>
				450
				451	<pre><code class="language-html prettyprint"><!-- Recommended -->
				452	<a class="maia-button maia-button-secondary">Sign in</a>
				453	</code></pre>
				454
				455	<h2 id="CSS">4 CSS</h2>
				456
				457	<h3 id="CSS_Style_Rules">4.1 CSS Style Rules</h3>
				458
				459	<h4 id="CSS_Validity">4.1.1 CSS Validity</h4>
				460
				461	<p>Use valid CSS where possible.</p>
				462
				463	<p>Unless dealing with CSS validator bugs or requiring proprietary syntax, use
				464	valid CSS code.</p>
				465
				466	<p>
				467
				468	Use tools such as the <a href="https://jigsaw.w3.org/css-validator/">W3C CSS validator</a>
				469	to test.
				470	</p>
				471
				472	<p>Using valid CSS is a measurable baseline quality attribute that allows to spot
				473	CSS code that may not have any effect and can be removed, and that ensures
				474	proper CSS usage.</p>
				475
				476	<h4 id="ID_and_Class_Naming">4.1.2 ID and Class Naming</h4>
				477
				478	<p>Use meaningful or generic ID and class names.</p>
				479
				480	<p>Instead of presentational or cryptic names, always use ID and class names that
				481	reflect the purpose of the element in question, or that are otherwise generic.</p>
				482
				483	<p>Names that are specific and reflect the purpose of the element should be
				484	preferred as these are most understandable and the least likely to change.</p>
				485
				486	<p>Generic names are simply a fallback for elements that have no particular or no
				487	meaning different from their siblings. They are typically needed as “helpers.”</p>
				488
				489	<p>Using functional or generic names reduces the probability of unnecessary
				490	document or template changes.</p>
				491
				492	<pre><code class="language-css prettyprint badcode">/* Not recommended: meaningless */
				493	#yee-1901 {}
				494
				495	/* Not recommended: presentational */
				496	.button-green {}
				497	.clear {}
				498	</code></pre>
				499
				500	<pre><code class="language-css prettyprint">/* Recommended: specific */
				501	#gallery {}
				502	#login {}
				503	.video {}
				504
				505	/* Recommended: generic */
				506	.aux {}
				507	.alt {}
				508	</code></pre>
				509
				510	<h4 id="ID_and_Class_Name_Style">4.1.3 ID and Class Name Style</h4>
				511
				512	<p>Use ID and class names that are as short as possible but as long as necessary.</p>
				513
				514	<p>Try to convey what an ID or class is about while being as brief as possible.</p>
				515
				516	<p>Using ID and class names this way contributes to acceptable levels of
				517	understandability and code efficiency.</p>
				518
				519	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				520	#navigation {}
				521	.atr {}
				522	</code></pre>
				523
				524	<pre><code class="language-css prettyprint">/* Recommended */
				525	#nav {}
				526	.author {}
				527	</code></pre>
				528
				529	<h4 id="Type_Selectors">4.1.4 Type Selectors</h4>
				530
				531	<p>Avoid qualifying ID and class names with type selectors.</p>
				532
				533	<p>Unless necessary (for example with helper classes), do not use element names in
				534	conjunction with IDs or classes.</p>
				535
				536	<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>
				537
				538	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				539	ul#example {}
				540	div.error {}
				541	</code></pre>
				542
				543	<pre><code class="language-css prettyprint">/* Recommended */
				544	#example {}
				545	.error {}
				546	</code></pre>
				547
				548	<h4 id="Shorthand_Properties">4.1.5 Shorthand Properties</h4>
				549
				550	<p>Use shorthand properties where possible.</p>
				551
				552	<p>CSS offers a variety of <a href="https://www.w3.org/TR/CSS21/about.html#shorthand">shorthand</a>
				553	properties (like <code>font</code>) that should be used whenever possible, even in cases
				554	where only one value is explicitly set.</p>
				555
				556	<p>Using shorthand properties is useful for code efficiency and understandability.</p>
				557
				558	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				559	border-top-style: none;
				560	font-family: palatino, georgia, serif;
				561	font-size: 100%;
				562	line-height: 1.6;
				563	padding-bottom: 2em;
				564	padding-left: 1em;
				565	padding-right: 1em;
				566	padding-top: 0;
				567	</code></pre>
				568
				569	<pre><code class="language-css prettyprint">/* Recommended */
				570	border-top: 0;
				571	font: 100%/1.6 palatino, georgia, serif;
				572	padding: 0 1em 2em;
				573	</code></pre>
				574
				575	<h4 id="0_and_Units">4.1.6 0 and Units</h4>
				576
				577	<p>Omit unit specification after “0” values, unless required.</p>
				578
				579	<p>Do not use units after <code>0</code> values unless they are required.</p>
				580
				581	<pre><code class="language-css prettyprint">flex: 0px; /* This flex-basis component requires a unit. */
				582	flex: 1 1 0px; /* Not ambiguous without the unit, but needed in IE11. */
				583	margin: 0;
				584	padding: 0;
				585	</code></pre>
				586
				587	<h4 id="Leading_0s">4.1.7 Leading 0s</h4>
				588
				589	<p>Omit leading “0”s in values.</p>
				590
				591	<p>Do not use put <code>0</code>s in front of values or lengths between -1 and 1.</p>
				592
				593	<pre><code class="language-css prettyprint">font-size: .8em;
				594	</code></pre>
				595
				596	<h4 id="Hexadecimal_Notation">4.1.8 Hexadecimal Notation</h4>
				597
				598	<p>Use 3 character hexadecimal notation where possible.</p>
				599
				600	<p>For color values that permit it, 3 character hexadecimal notation is shorter and
				601	more succinct.</p>
				602
				603	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				604	color: #eebbcc;
				605	</code></pre>
				606
				607	<pre><code class="language-css prettyprint">/* Recommended */
				608	color: #ebc;
				609	</code></pre>
				610
				611	<h4 id="Prefixes">4.1.9 Prefixes</h4>
				612
				613	<p>Prefix selectors with an application-specific prefix (optional).</p>
				614
				615	<p>In large projects as well as for code that gets embedded in other projects or on
				616	external sites use prefixes (as namespaces) for ID and class names. Use short,
				617	unique identifiers followed by a dash.</p>
				618
				619	<p></p>
				620
				621	<p></p>
				622
				623	<p>Using namespaces helps preventing naming conflicts and can make maintenance
				624	easier, for example in search and replace operations.</p>
				625
				626	<pre><code class="language-css prettyprint">.adw-help {} /* AdWords */
				627	#maia-note {} /* Maia */
				628	</code></pre>
				629
				630	<h4 id="ID_and_Class_Name_Delimiters">4.1.10 ID and Class Name Delimiters</h4>
				631
				632	<p>Separate words in ID and class names by a hyphen.</p>
				633
				634	<p>Do not concatenate words and abbreviations in selectors by any characters
				635	(including none at all) other than hyphens, in order to improve understanding
				636	and scannability.</p>
				637
				638	<pre><code class="language-css prettyprint badcode">/* Not recommended: does not separate the words “demo” and “image” */
				639	.demoimage {}
				640
				641	/* Not recommended: uses underscore instead of hyphen */
				642	.error_status {}
				643	</code></pre>
				644
				645	<pre><code class="language-css prettyprint">/* Recommended */
				646	#video-id {}
				647	.ads-sample {}
				648	</code></pre>
				649
				650	<h4 id="Hacks">4.1.11 Hacks</h4>
				651
				652	<p>Avoid user agent detection as well as CSS “hacks”—try a different approach
				653	first.</p>
				654
				655	<p>It’s tempting to address styling differences over user agent detection or
				656	special CSS filters, workarounds, and hacks. Both approaches should be
				657	considered last resort in order to achieve and maintain an efficient and
				658	manageable code base. Put another way, giving detection and hacks a free pass
				659	will hurt projects in the long run as projects tend to take the way of least
				660	resistance. That is, allowing and making it easy to use detection and hacks
				661	means using detection and hacks more frequently—and more frequently is too
				662	frequently.</p>
				663
				664	<p></p>
				665
				666	<p></p>
				667
				668	<h3 id="CSS_Formatting_Rules">4.2 CSS Formatting Rules</h3>
				669
				670	<h4 id="Declaration_Order">4.2.1 Declaration Order</h4>
				671
				672	<p>Alphabetize declarations.</p>
				673
				674	<p>Put declarations in alphabetical order in order to achieve consistent code in a
				675	way that is easy to remember and maintain.</p>
				676
				677	<p>Ignore vendor-specific prefixes for sorting purposes. However, multiple
				678	vendor-specific prefixes for a certain CSS property should be kept sorted (e.g.
				679	-moz prefix comes before -webkit).</p>
				680
				681	<pre><code class="language-css prettyprint">background: fuchsia;
				682	border: 1px solid;
				683	-moz-border-radius: 4px;
				684	-webkit-border-radius: 4px;
				685	border-radius: 4px;
				686	color: black;
				687	text-align: center;
				688	text-indent: 2em;
				689	</code></pre>
				690
				691	<h4 id="Block_Content_Indentation">4.2.2 Block Content Indentation</h4>
				692
				693	<p>Indent all block content.</p>
				694
				695	<p>Indent all <a href="https://www.w3.org/TR/CSS21/syndata.html#block">block content</a>,
				696	that is rules within rules as well as declarations, so to reflect hierarchy and
				697	improve understanding.</p>
				698
				699	<pre><code class="language-css prettyprint">@media screen, projection {
				700
				701	html {
				702	background: #fff;
				703	color: #444;
				704	}
				705
				706	}
				707	</code></pre>
				708
				709	<h4 id="Declaration_Stops">4.2.3 Declaration Stops</h4>
				710
				711	<p>Use a semicolon after every declaration.</p>
				712
				713	<p>End every declaration with a semicolon for consistency and extensibility
				714	reasons.</p>
				715
				716	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				717	.test {
				718	display: block;
				719	height: 100px
				720	}
				721	</code></pre>
				722
				723	<pre><code class="language-css prettyprint">/* Recommended */
				724	.test {
				725	display: block;
				726	height: 100px;
				727	}
				728	</code></pre>
				729
				730	<h4 id="Property_Name_Stops">4.2.4 Property Name Stops</h4>
				731
				732	<p>Use a space after a property name’s colon.</p>
				733
				734	<p>Always use a single space between property and value (but no space between
				735	property and colon) for consistency reasons.</p>
				736
				737	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				738	h3 {
				739	font-weight:bold;
				740	}
				741	</code></pre>
				742
				743	<pre><code class="language-css prettyprint">/* Recommended */
				744	h3 {
				745	font-weight: bold;
				746	}
				747	</code></pre>
				748
				749	<h4 id="Declaration_Block_Separation">4.2.5 Declaration Block Separation</h4>
				750
				751	<p>Use a space between the last selector and the declaration block.</p>
				752
				753	<p>Always use a single space between the last selector and the opening brace that
				754	begins the <a href="https://www.w3.org/TR/CSS21/syndata.html#rule-sets">declaration block</a>.</p>
				755
				756	<p>The opening brace should be on the same line as the last selector in a given
				757	rule.</p>
				758
				759	<pre><code class="language-css prettyprint badcode">/* Not recommended: missing space */
				760	#video{
				761	margin-top: 1em;
				762	}
				763
				764	/* Not recommended: unnecessary line break */
				765	#video
				766	{
				767	margin-top: 1em;
				768	}
				769	</code></pre>
				770
				771	<pre><code class="language-css prettyprint">/* Recommended */
				772	#video {
				773	margin-top: 1em;
				774	}
				775	</code></pre>
				776
				777	<h4 id="Selector_and_Declaration_Separation">4.2.6 Selector and Declaration Separation</h4>
				778
				779	<p>Separate selectors and declarations by new lines.</p>
				780
				781	<p>Always start a new line for each selector and declaration.</p>
				782
				783	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				784	a:focus, a:active {
				785	position: relative; top: 1px;
				786	}
				787	</code></pre>
				788
				789	<pre><code class="language-css prettyprint">/* Recommended */
				790	h1,
				791	h2,
				792	h3 {
				793	font-weight: normal;
				794	line-height: 1.2;
				795	}
				796	</code></pre>
				797
				798	<h4 id="Rule_Separation">4.2.7 Rule Separation</h4>
				799
				800	<p>Separate rules by new lines.</p>
				801
				802	<p>Always put a blank line (two line breaks) between rules.</p>
				803
				804	<pre><code class="language-css prettyprint">html {
				805	background: #fff;
				806	}
				807
				808	body {
				809	margin: auto;
				810	width: 50%;
				811	}
				812	</code></pre>
				813
				814	<h4 id="CSS_Quotation_Marks">4.2.8 CSS Quotation Marks</h4>
				815
				816	<p>Use single quotation marks for attribute selectors and property values.</p>
				817
				818	<p>Use single (<code>''</code>) rather than double (<code>""</code>) quotation marks for attribute
				819	selectors or property values. Do not use quotation marks in URI values
				820	(<code>url()</code>).</p>
				821
				822	<p>Exception: If you do need to use the <code>@charset</code> rule, use double quotation
				823	marks—<a href="https://www.w3.org/TR/CSS21/syndata.html#charset">single quotation marks are not permitted</a>.</p>
				824
				825	<pre><code class="language-css prettyprint badcode">/* Not recommended */
				826	@import url("https://www.google.com/css/maia.css");
				827
				828	html {
				829	font-family: "open sans", arial, sans-serif;
				830	}
				831	</code></pre>
				832
				833	<pre><code class="language-css prettyprint">/* Recommended */
				834	@import url(https://www.google.com/css/maia.css);
				835
				836	html {
				837	font-family: 'open sans', arial, sans-serif;
				838	}
				839	</code></pre>
				840
				841	<h3 id="CSS_Meta_Rules">4.3 CSS Meta Rules</h3>
				842
				843	<h4 id="Section_Comments">4.3.1 Section Comments</h4>
				844
				845	<p>Group sections by a section comment (optional).</p>
				846
				847	<p>If possible, group style sheet sections together by using comments. Separate
				848	sections with new lines.</p>
				849
				850	<pre><code class="language-css prettyprint">/* Header */
				851
				852	#adw-header {}
				853
				854	/* Footer */
				855
				856	#adw-footer {}
				857
				858	/* Gallery */
				859
				860	.adw-gallery {}
				861	</code></pre>
				862
				863
				864
				865	<p></p>
				866
				867	<p></p>
				868
				869
				870
				871	<p></p>
				872
				873	<p></p>
				874
				875	<pre></pre>
				876
				877
				878
				879
				880
				881	<p></p>
				882
				883	<p></p>
				884
Tony Ruscoe	a1773f9	2017-02-24 13:22:25 +0000	[diff] [blame]	885	<h2 id="Parting_Words">Parting Words</h2>
Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	886
Tony Ruscoe	a1773f9	2017-02-24 13:22:25 +0000	[diff] [blame]	887	<p><em>Be consistent.</em></p>
Tony Ruscoe	d0960a4	2017-02-24 12:31:41 +0000	[diff] [blame]	888
				889	<p>If you’re editing code, take a few minutes to look at the code around you and
				890	determine its style. If they use spaces around all their arithmetic operators,
				891	you should too. If their comments have little boxes of hash marks around them,
				892	make your comments have little boxes of hash marks around them too.</p>
				893
				894	<p>The point of having style guidelines is to have a common vocabulary of coding so
				895	people can concentrate on what you’re saying rather than on how you’re saying
				896	it. We present global style rules here so people know the vocabulary, but local
				897	style is also important. If code you add to a file looks drastically different
				898	from the existing code around it, it throws readers out of their rhythm when
				899	they go to read it. Avoid this.</p>
				900	</div>
				901	</body>
Tony Ruscoe	ad6dee8	2017-02-27 08:16:24 +0000	[diff] [blame]	902	</html>