+ + Revision 2.1 +
+ ++ Hooray! Now you know you can expand points to get more + details. Alternatively, there’s a “toggle all” at the + top of this document. +
+ ++ 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. +
++ Don’t use tabs or mix tabs and spaces for indentation. +
+
+ All code has to be lowercase: this applies to element names,
+ attributes, attribute values (unless
+ text/CDATA), selectors, properties, and
+ property values (with the exception of strings).
+
+ Trailing white spaces are unnecessary and can complicate + diffs. +
++ 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 Character + Sets & Encodings in XHTML, 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.
+
+ 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.
+
+ HTML5 (HTML syntax) is preferred for all HTML documents:
+ <!DOCTYPE html>.
+
+ (It is 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.)
+
+ 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. +
+
+ 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. +
+ +
+ 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="".)
+
+ 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. +
+ +
+ 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).
+
+ 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 is significantly different + from what web developers are typically taught. For + consistency and simplicity reasons it is best served + omitting all optional tags, not just a selection.) +
+type attributes for style sheets and scripts.
+
+ 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.
+
+ 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 is acceptable to put all li elements in one
+ line. A linter is encouraged to throw a warning instead of
+ an error.)
+
+ 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. +
+ ++ 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. +
++ 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. +
+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. +
+
+ 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. +
+
+ Do not use units after 0 values unless they are
+ required.
+
+ Do not use put 0s in front of values or lengths
+ between -1 and 1.
+
+ Do not use quotation marks ("",
+ '') with url().
+
+ For color values that permit it, 3 character hexadecimal + notation is shorter and more succinct. +
++ 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. +
++ 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. +
++ It is 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. +
+ + + ++ 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). +
++ Indent all block + content, that is rules within rules as well as declarations, so to + reflect hierarchy and improve understanding. +
++ End every declaration with a semicolon for consistency and + extensibility reasons. +
++ Always use a single space between property and value (but no + space between property and colon) for consistency reasons. +
++ Always start a new line for each selector and declaration. +
++ Always put a line between rules. +
++ If possible, group style sheets sections together by using + comments. Separate sections with new lines. +
++ Be consistent. +
++ 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. +
++ Revision 2.1 +
+ +