Home

HTML code guide

Every line of code should appear to be written by a single person, no matter the number of contributors.

Table of contents

Syntax
Formatting
Quotation Marks
Spacing
Reducing markup
Linting/HTML Validity
HTML5 DOCTYPE
Language attribute
Character encoding
IE compatibility mode
CSS and JS includes
Attribute order
Boolean attributes
Multimedia Fallback
Forms
Comments
Action items
Protocol
Separation of Concerns

Purpose

=> 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.
=> Use HTML elements for what they are meant to be used for.
=> Use elements (sometimes incorrectly called “tags”) for what they have been created for.

Using HTML according to its purpose is important for accessibility, reuse, and code efficiency reasons.

Syntax

Use soft tabs with two spaces
Nested elements should be indented once (two spaces)
Don't include a trailing slash in self-closing elements (HTML5 spec)
Don't omit optional closing tags

<html>
  <head>
    <title>worldremit</title>
  </head>
  <body>
    <img src="images/company-logo.png" alt="Company">
    <h1 class="hello-world">Hello, world!</h1>
  </body>
</html>

Formatting

Always use the minimal, versionless and lowercase doctype.
Always define which language the page is written in.
Always include html, head, and body tags.
Use a new line for every block, list, or table element, and indent every such child element.
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.
Always define the character encoding. Most pages should use utf-8. The encoding should be defined as early as possible and must be in the first 1024 bytes of the document.
Always use lowercase names for elements and attributes.
Always quote attributes values. Always use double quotes instead of single quotes.
Self-closing elements must not be closed.
Optional attributes must be omitted, for file size optimization and scannability purposes.
Always include an alt attribute for images

<blockquote>
  <p><em>Space</em>, the final frontier.</p>
</blockquote>

<ul>
  <li>Moe
  <li>Larry
  <li>Curly
</ul>

<table>
  <thead>
    <tr>
      <th scope="col">Income
      <th scope="col">Taxes
  <tbody>
    <tr>
      <td>$ 5.00
      <td>$ 4.50
</table>

Quotation Marks

When quoting attributes values, use double quotation marks.
Use double ("") rather than single quotation marks ('') around attribute values.

<!-- Not recommended -->
<a class='maia-button maia-button-secondary'>Sign in</a>

<!-- Recommended -->
<a class="maia-button maia-button-secondary">Sign in</a>

Spacing

In general, it is encourages liberal spacing for improved human readability.

Indentation with tabs.
Don't indent the direct children of html, body, script, or style. Indent everything else.
No whitespace at the end of line or on blank lines.
Separate attributes with a space.

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Sample Page</title>

    <link rel="stylesheet" href="/style.css">
    <style>
    body {
        font-size: 100em;
    }
    </style>

    <script src="/jslibrary.js"></script>
    <script>
    $( function() {
        $( "p" ).text( $.fn.jquery );
    } );
    </script>
</head>
<body>

<section>
    <p>Code guides are awesome!<p>
</section>

</body>
</html>

Reducing markup

Whenever possible, avoid superfluous parent elements when writing HTML.
Many times this require iteration and refactoring, but produces less HTML.

<!-- Bad HTML -->
<span class="avatar">
    <img src="assets/img/img.png" alt="Jane Doe">
</span>

<!-- Good HTML -->
<img class="avatar" src="assets/img/img.png" alt="Jane Doe">

Linting/ HTML Validity

Use a linter to detect errors and potential problems.
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.

HTML5 doctype

Enforce standards mode and more consistent rendering in every browser possible

<!doctype html>
<html>
  <head>
  </head>
</html>

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.

<html lang="en-us">
  <!-- ... -->
</html>

Character encoding

Ensure proper rendering of the content by declaring an explicit character encoding.

<head>
  <meta charset="UTF-8">
</head>

IE compatibility mode

IE supports the use of a document compatibility <meta> tag to specify what version of IE the page should rendered as.
It's most useful to instruct IE to use the latest supported mode with edge mode.

CSS and JS includes

There is no need to specify a type when including CSS and JS files as text/css and text/javascript are their respective defaults (HTML5 spec)

<!-- Not recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css"
  type="text/css">

<!-- Recommended -->
<link rel="stylesheet" href="//www.google.com/css/maia.css">

Attribute order

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

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

Classes make for great reusable components, so they come first.
Ids are more specific and should be used sparingly. so they come second.

Boolean attributes

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

<input type="text" disabled>

<input type="checkbox" value="1" checked>

<select>
  <option value="1" selected>1</option>
</select>

Multimedia Fallback

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.

<!-- Not recommended -->
<img src="spreadsheet.png">
<!-- Recommended -->
<img src="spreadsheet.png" alt="Spreadsheet screenshot.">

Forms

Always include a for attribute for label elements. This is more robust than implicit labeling across browsers and assistive technologies.

<!-- Bad Example -->
<label><input type="radio" name="input" value="first"> First</label>

<!-- Good Example -->
<input type="radio" name="input" id="input-1" value="first">
<label for="input-1">First</label>

Don't use the placeholder attribute for labeling; always use a label element.

<!-- Bad Example -->
<input type="text" id="name" placeholder="Enter your name">

<!-- Good Example -->
<label for="name">Name</label>
<input id="name" type="text" placeholder="Jane Doe">

Comments

Explain code as needed, where possible.
Use comments to explain code: What does it cover, what purpose does it serve, why is respective solution used or preferred?
Comments are always preceded by a blank line.
Comments start with a capital first letter, but don't require a period at the end, unless you're writing full sentences.
There must be a single space between the comment token and the comment text.

When comments take up multiple lines, break line after .

<!-- Good single line comment -->

<!--
Good example of a multi-line comment.
If your comment takes up multiple lines, please do this.
-->

Action items

Mark todos and action items with TODO.
Highlight todos by using the keyword TODO only, not other common formats like @@.

<!-- TODO: remove optional tags -->
<ul>
  <li>Apples</li>
  <li>Oranges</li>
</ul>

Protocol

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.

<!-- Not recommended -->
<script src="https://www.google.com/js/gweb/analytics/autotrack.js"></script>
<!-- Recommended -->
<script src="//www.google.com/js/gweb/analytics/autotrack.js"></script>

Separation of Concerns

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.

<!-- Not recommended -->
<!DOCTYPE html>
<title>HTML sucks</title>
<link rel="stylesheet" href="base.css" media="screen">
<link rel="stylesheet" href="grid.css" media="screen">
<link rel="stylesheet" href="print.css" media="print">
<h1 style="font-size: 1em;">HTML sucks</h1>
<p>I’ve read about this on a few sites but now I’m sure:
  <u>HTML is stupid!!1</u>
<center>I can’t believe there’s no way to control the styling of
  my website without doing everything all over again!</center>

<!-- Recommended -->
<!DOCTYPE html>
<title>My first CSS-only redesign</title>
<link rel="stylesheet" href="default.css">
<h1>My first CSS-only redesign</h1>
<p>I’ve read about this on a few sites but today I’m actually
  doing it: separating concerns and avoiding anything in the HTML of
  my website that is presentational.
<p>It’s awesome!

Development Guides

Provide feedback

Saved searches

Use saved searches to filter your results more quickly