Google HTML/CSS Style Guide
-1 Background
+Background
This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. @@ -19,17 +19,16 @@
1 Background
Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained. -2 General
+General
-2.1 General Style Rules
+General Style Rules
-2.1.1 Protocol
+Protocol
Use HTTPS for embedded resources where possible.
-Always use HTTPS (https:) for images and other media
-files, style sheets, and scripts, unless the respective files are not available
-over HTTPS.
Always use HTTPS (https:) for images and other media files, style sheets, and
+scripts, unless the respective files are not available over HTTPS.
<!-- Not recommended: omits the protocol -->
<script src="//ajax.googleapis.com/ajax/libs/jquery/3.4.0/jquery.min.js"></script>
@@ -53,9 +52,9 @@ 2.1.1 Protocol
@import 'https://fonts.googleapis.com/css?family=Open+Sans';
2.2 General Formatting Rules
+General Formatting Rules
-2.2.1 Indentation
+Indentation
Indent by 2 spaces at a time.
@@ -72,7 +71,7 @@2.2.1 Indentation
} -2.2.2 Capitalization
+Capitalization
Use only lowercase.
@@ -96,7 +95,7 @@2.2.2 Capitalization
color: #e5e5e5; -2.2.3 Trailing Whitespace
+Trailing Whitespace
Remove trailing white spaces.
@@ -110,9 +109,9 @@2.2.3 Trailing Whitespace
<p>Yes please. -2.3 General Meta Rules
+General Meta Rules
-2.3.1 Encoding
+Encoding
Use UTF-8 (no BOM).
@@ -123,10 +122,10 @@2.3.1 Encoding
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.)
+(More on encodings and when and how to specify them can be found in +Handling character encodings in HTML and CSS.)
-2.3.2 Comments
+Comments
Explain code as needed, where possible.
@@ -137,7 +136,7 @@2.3.2 Comments
demand fully documented code. Mileage may vary heavily for HTML and CSS code and depends on the project’s complexity.) -2.3.3 Action Items
+Action Items
Mark todos and action items with TODO.
2.3.3 Action Items
</ul> -3 HTML
+HTML
-3.1 HTML Style Rules
+HTML Style Rules
-3.1.1 Document Type
+Document Type
Use HTML5.
@@ -174,21 +173,19 @@3.1.1 Document Type
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 />.
Although fine with HTML, do not close void elements, i.e. write <br>, not <br
+/>.
3.1.2 HTML Validity
+HTML Validity
Use valid HTML where possible.
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. -
+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 @@ -206,7 +203,7 @@
3.1.2 HTML Validity
<article>This is only a test.</article> -3.1.3 Semantics
+Semantics
Use HTML according to its purpose.
@@ -225,7 +222,7 @@3.1.3 Semantics
<a href="recommendations/">All recommendations</a> -3.1.4 Multimedia Fallback
+Multimedia Fallback
Provide alternative contents for multimedia.
@@ -249,7 +246,7 @@3.1.4 Multimedia Fallback
<img src="spreadsheet.png" alt="Spreadsheet screenshot."> -3.1.5 Separation of Concerns
+Separation of Concerns
Separate structure from presentation from behavior.
@@ -292,13 +289,13 @@3.1.5 Separation of Concerns
<p>It’s awesome! -3.1.6 Entity References
+Entity References
Do not use entity references.
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.
☺, 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).
3.1.6 Entity References
The currency symbol for the Euro is “€”. -3.1.7 Optional Tags
+Optional Tags
Omit optional tags (optional).
For file size optimization and scannability purposes, consider omitting optional -tags. The HTML5 specification +tags. The +HTML5 specification defines what tags can be omitted.
(This approach may require a grace period to be established as a wider guideline @@ -342,7 +340,7 @@
3.1.7 Optional Tags
<p>Qed. -3.1.8 type Attributes
+type Attributes
Omit type attributes for style sheets and scripts.
3.1.8 type Attributes
Specifying type attributes in these contexts is not necessary as HTML5 implies
text/css
-and text/javascript
+and
+text/javascript
as defaults. This can be safely done even for older browsers.
<!-- Not recommended -->
@@ -372,9 +371,9 @@ 3.1.8 type Attributes
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
3.2 HTML Formatting Rules
+HTML Formatting Rules
-3.2.1 General Formatting
+General Formatting
Use a new line for every block, list, or table element, and indent every such child element.
@@ -413,7 +412,7 @@3.2.1 General Formatting
</table> -3.2.2 HTML Line-Wrapping
+HTML Line-Wrapping
Break long lines (optional).
@@ -443,7 +442,7 @@3.2.2 HTML Line-Wrapping
</md-progress-circular> -3.2.3 HTML Quotation Marks
+HTML Quotation Marks
When quoting attributes values, use double quotation marks.
@@ -458,28 +457,26 @@3.2.3 HTML Quotation Marks
<a class="maia-button maia-button-secondary">Sign in</a> -4 CSS
+CSS
-4.1 CSS Style Rules
+CSS Style Rules
-4.1.1 CSS Validity
+CSS Validity
Use valid CSS where possible.
Unless dealing with CSS validator bugs or requiring proprietary syntax, use valid CSS code.
-- -Use tools such as the W3C CSS validator -to test. -
+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.
-4.1.2 ID and Class Naming
+ID and Class Naming
Use meaningful or generic ID and class names.
@@ -513,7 +510,7 @@4.1.2 ID and Class Naming
.alt {} -4.1.3 ID and Class Name Style
+ID and Class Name Style
Use ID and class names that are as short as possible but as long as necessary.
@@ -532,14 +529,15 @@4.1.3 ID and Class Name Style
.author {} -4.1.4 Type Selectors
+Type Selectors
Avoid qualifying ID and class names with type selectors.
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.
+Avoiding unnecessary ancestor selectors is useful for +performance reasons.
/* Not recommended */
ul#example {}
@@ -551,11 +549,12 @@ 4.1.4 Type Selectors
.error {}
4.1.5 Shorthand Properties
+Shorthand Properties
Use shorthand properties where possible.
-CSS offers a variety of shorthand +
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.
4.1.5 Shorthand Properties
padding: 0 1em 2em; -4.1.6 0 and Units
+0 and Units
Omit unit specification after “0” values, unless required.
@@ -590,7 +589,7 @@4.1.6 0 and Units
padding: 0; -4.1.7 Leading 0s
+Leading 0s
Omit leading “0”s in values.
@@ -599,7 +598,7 @@4.1.7 Leading 0s
font-size: .8em;
4.1.8 Hexadecimal Notation
+Hexadecimal Notation
Use 3 character hexadecimal notation where possible.
@@ -614,7 +613,7 @@4.1.8 Hexadecimal Notation
color: #ebc; -4.1.9 Prefixes
+Prefixes
Prefix selectors with an application-specific prefix (optional).
@@ -629,7 +628,7 @@4.1.9 Prefixes
#maia-note {} /* Maia */ -4.1.10 ID and Class Name Delimiters
+ID and Class Name Delimiters
Separate words in ID and class names by a hyphen.
@@ -649,7 +648,7 @@4.1.10 ID and Class Name Delimiters
.ads-sample {} -4.1.11 Hacks
+Hacks
Avoid user agent detection as well as CSS “hacks”—try a different approach first.
@@ -663,9 +662,9 @@4.1.11 Hacks
means using detection and hacks more frequently—and more frequently is too frequently. -4.2 CSS Formatting Rules
+CSS Formatting Rules
-4.2.1 Declaration Order
+Declaration Order
Alphabetize declarations.
@@ -686,11 +685,12 @@4.2.1 Declaration Order
text-indent: 2em; -4.2.2 Block Content Indentation
+Block Content Indentation
Indent all block content.
-Indent all block content, +
Indent all +block content, that is rules within rules as well as declarations, so to reflect hierarchy and improve understanding.
@@ -704,7 +704,7 @@4.2.2 Block Content Indentation
} -4.2.3 Declaration Stops
+Declaration Stops
Use a semicolon after every declaration.
@@ -725,7 +725,7 @@4.2.3 Declaration Stops
} -4.2.4 Property Name Stops
+Property Name Stops
Use a space after a property name’s colon.
@@ -744,12 +744,13 @@4.2.4 Property Name Stops
} -4.2.5 Declaration Block Separation
+Declaration Block Separation
Use a space between the last selector and the declaration block.
Always use a single space between the last selector and the opening brace that -begins the declaration block.
+begins the +declaration block.The opening brace should be on the same line as the last selector in a given rule.
@@ -772,7 +773,7 @@4.2.5 Declaration Block Separation
} -4.2.6 Selector and Declaration Separation
+Selector and Declaration Separation
Separate selectors and declarations by new lines.
@@ -793,7 +794,7 @@4.2.6 Selector and Declaration Sepa
}
-4.2.7 Rule Separation
+Rule Separation
Separate rules by new lines.
@@ -809,7 +810,7 @@4.2.7 Rule Separation
} -4.2.8 CSS Quotation Marks
+CSS Quotation Marks
Use single ('') rather than double ("") quotation marks for attribute
selectors and property values.
4.2.8 CSS Quotation Marks
} -4.3 CSS Meta Rules
+CSS Meta Rules
-4.3.1 Section Comments
+Section Comments
Group sections by a section comment (optional).
diff --git a/javaguide.css b/javaguide.css index 10cd73024..39a7bc638 100644 --- a/javaguide.css +++ b/javaguide.css @@ -570,3 +570,32 @@ li.toc_entry a { .toc td.two_columns { border-width: 0px; } + +/* Numbered sections */ + +h1 { + counter-reset: h2; +} + +h2.numbered { + counter-reset: h3; +} + +h3.numbered { + counter-reset: h4; +} + +h2.numbered::before { + content: counter(h2) ' '; + counter-increment: h2; +} + +h3.numbered::before { + content: counter(h2) '.' counter(h3) ' '; + counter-increment: h3; +} + +h4.numbered::before { + content: counter(h2) '.' counter(h3) '.' counter(h4) ' '; + counter-increment: h4; +}