HTML - HealthTeacher/style-guide GitHub Wiki

Much of this was inspired by idiomatic-html. Please add to this guide if you find any particular patterns or styles that we've adopted internally.

Table of Contents

  1. General principles
  2. Whitespace
  3. Format
  4. Attribute order
  5. Naming
  6. Practical example

General principles

  • All code in any code-base should look like a single person typed it, no matter how many people contributed.
  • Strictly enforce the agreed upon style.
  • If in doubt when deciding upon a style, use existing, common patterns.

Whitespace

Only one style should exist across the entire source of your code-base. Always be consistent in your use of whitespace. Use whitespace to improve readability.

  • Never mix spaces and tabs for indentation.
  • Use soft indents (spaces) NOT real tabs.
  • Use 2 spaces for indents.

Tip: configure your editor to "show invisibles". This will allow you to eliminate end of line whitespace, eliminate unintended blank line whitespace, and avoid polluting commits.

Format

  • Keep line-length to 100 columns or fewer.
  • Always use lowercase tag and attribute names.
  • Write one discrete element per line.
  • Use one additional level of indentation for each nested element.
  • Use valueless boolean attributes (e.g. checked rather than checked="checked").
  • Always use double quotes to quote attribute values.
  • Omit the type attributes from link stylesheet, style and script elements.

Example:

<div class="Tweet">
  <a href="path/to/somewhere">
    <img src="path/to/image.png" alt="">
  </a>
  <p>[tweet text]</p>
  <button disabled>Reply</button>
</div>

Exceptions and slight deviations

Elements with multiple attributes can have attributes arranged across multiple lines in an effort to improve readability and produce more useful diffs.

Example:

<a
  class="[value]"
  data-action="[value]"
  data-id="[value]"
  href="[url]"
>
  <span>[text]</span>
</a>

Attribute order

HTML attributes should be listed alphabetically.

Example:

<a
  alt="[value]"
  class="[value]"
  data-name="[value]"
  id="[value]"
  href="[url]"
>
  [text]
</a>

Naming

Naming is hard, but very important. It's a crucial part of the process of developing a maintainable code base, and ensuring that you have a relatively scalable interface between your HTML and CSS/JS.

  • Use clear, thoughtful, and appropriate names for HTML classes. The names should be informative both within HTML and CSS files.
  • Avoid systematic use of abbreviated class names. Don't make things difficult to understand.

Example with bad names:

<div class="cb s-scr"></div>
.cb {
  background: #000;
}

.s-scr {
  overflow: auto;
}

Example with better names:

<div class="ColumnBody u-isScrollable"></div>
.ColumnBody {
  background: #000;
}

.u-isScrollable {
  overflow: auto;
}

Practical example

An example of various conventions.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>Document</title>
    <link rel="stylesheet" href="main.css">
    <script src="main.js"></script>
  </head>
  <body>
    <article class="Post" id="1234">
      <time class="Timestamp">March 15, 2012</time>
      <a data-id="1234"
        data-analytics-category="[value]"
        data-analytics-action="[value]"
        href="[url]">[text]</a>
      <ul>
        <li>
          <a href="[url]">[text]</a>
          <img alt="[text]" src="[url]">
        </li>
        <li>
          <a href="[url]">[text]</a>
        </li>
      </ul>

      <a class="LinkComplex" href="[url]">
        <span class="LinkComplex-target">[text]</span>
        [text]
      </a>

      <input value="text" readonly>
    </article>
  </body>
</html>
⚠️ **GitHub.com Fallback** ⚠️