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 Handling character encodings in 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™s 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.)
Although fine with HTML, do not close void elements, i.e. write<br>, not <br />.
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 viacanvas, 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™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.)
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 impliestext/css
andtext/javascript
as defaults. This can be safely done even for older browsers.
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.
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™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.
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 use a single space between the last selector and the opening brace that begins the declaration block.
The opening brace should be on the same line as the last selector in a given rule.
Always start a new line for each selector and declaration.
Always put a blank line (two line breaks) between rules.
Use single ('') rather than double ("")
quotation marks for attribute selectors or property values. Do not
use quotation marks in URI values (url()).
Exception: If you do need to use the @charset rule,
use double quotation marks”single
quotation marks are not permitted.
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.