Code Guide

Syntax

• Use soft tabs with two spaces.
• Nested elements should be indented once (two spaces).
• Lines should not exceed 100 characters.
• Always use double quotes, never single quotes, on attributes.
• Don't include a trailing slash in self-closing elements—the HTML5 spec says they're optional. That is, unless you're writing JSX for React components; JSX requires that all tags are closed, either with the trailing slash or with a closing tag.
• Don’t omit optional closing tags (e.g. </li> or </body>).
• Attribute values, particularly for the class, id and name attributes, should be in lower spine-case. Not snake_case. Not camelCase. Not, for the love of all that is good, some-unholy_combinationOfThem.

HTML5 doctype

Enforce standards mode and more consistent rendering in every browser possible with this simple doctype at the beginning of every HTML page.

Language attribute

From the HTML5 spec:

Authors are encouraged to specify a lang attribute on the root html element, giving the document's language. This aids speech synthesis tools to determine what pronunciations to use, translation tools to determine what rules to use, and so forth.

Read more about the lang attribute in the spec.

Head to Sitepoint for a list of language codes.

IE compatibility mode

Internet Explorer supports the use of a document compatibility <meta> tag to specify what version of IE the page should be rendered as. Unless circumstances require otherwise, it's most useful to instruct IE to use the latest supported mode with edge mode.

For more information, read this awesome Stack Overflow article.

Character encoding

Quickly and easily ensure proper rendering of your content by declaring an explicit character encoding. When doing so, you may avoid using character entities in your HTML, provided their encoding matches that of the document (generally UTF-8).

CSS and JavaScript includes

Per HTML5 spec, typically there is no need to specify a type when including CSS and JavaScript files as text/css and text/javascript are their respective defaults.

HTML5 spec links

• Using link
• Using style
• Using script

Practicality over purity

Strive to maintain HTML standards and semantics, but not at the expense of practicality. Use the least amount of markup with the fewest intricacies whenever possible.

Attribute order

HTML attributes should come in this particular order for easier reading of code.

• id, name
• class
• src, for, type, href, value
• title, alt
• role, aria-*
• data-*

IDs and names should be used sparingly and are intended to be used uniquely, so they come first. Classes denote groups and common behavior/styling, so they come second. Attributes that refer to other entities (src, href, for), further classify the item (type) or provide a value (value) come next. Then come attributes with supplementary information like title and alt. Finally, add the accessibility-related attributes, and any data attributes.

Boolean attributes

A boolean attribute is one that needs no declared value. XHTML required you to declare a value, but HTML5 has no such requirement.

For further reading, consult the WhatWG section on boolean attributes:

The presence of a boolean attribute on an element represents the true value, and the absence of the attribute represents the false value.

If you must include the attribute's value, and you don't need to, follow this WhatWG guideline:

If the attribute is present, its value must either be the empty string or […] the attribute's canonical name, with no leading or trailing whitespace.

In short, don't add a value.

Reducing markup

Whenever possible, avoid superfluous parent elements when writing HTML. Many times this requires iteration and refactoring, but produces less HTML. Take the following example:

Unnamed non-semantic elements

Do not add non-semantic elements like div or span to your markup without a name. Properly-used semantic elements like p, section, aside, etc. do not require a name, since they hint at their content.

This has the side-effect of making your CSS a lot more readable, since you’ll be using semantic selectors.

.fine-print {
  font-style: italic;
}

/* or */

small {
  font-style: italic;
}

is way more meaningful, and has less unintended consequences, than

p span {
  font-style: italic;
}

Naming and automated UI testing

Corollary to the previous section: think about how your markup will be accessed by an automated test. If an element on the page is likely to be accessed by an automated test, make sure to give it a meaningful name.

Someone writing a test to verify the correct count for the first code snippet would have to look for h1 strong (assuming use of CSS selectors), which could return more results than expected and throw off testing. It's also brittle and would have to be updated if the markup hierarchy was changed by, say, changing the h1 to an h2.

By contrast, the selector for the second code snippet would be .result-info .match-count, which is much easier to read and understand, and more flexible in the face of markup hierarchy changes, providing that the two elements were kept in the same ancestor-descendant relationship.

When markup hierarchy changes are made, it is up to the developer doing the changing to:

• Run automated tests, including integration tests, to verify that there is no breakage. If there is, it is the developer's responsibility to fix it.
• If the test suite suffering breakage is owned or maintained by someone else, it is the developer's responsibility to notify the maintainer of the tests that changes have been made to the markup.

Inline styles. Just no.

Unless you are writing HTML email, there is no excuse to use inline styles. Put your styles in a stylesheet, where they belong and where they won't cause you to get into a war of specificity with yourself.