HTML - acnorrisuk/coding-style-guide GitHub Wiki

Doctype & Meta Tags

The HTML5 doctype should be declared as the first line of the document

<!DOCTYPE html>

The language attribute should be added to the HTML tag as it benefits screen readers and search engines.

<html lang="en-GB">

The character encoding needs to appear in the first 1024 bytes of the file (See W3), so it's best to place this immediately after the opening head tag.

<meta charset="utf-8">

The viewport meta tag should not restrict scaling as this can cause issues on small screens where users may wish to zoom in to view content.

<!-- bad -->
<meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=1.0 user-scalable=no">

<!-- good -->
<meta name="viewport" content="width=device-width, initial-scale=1">

Semantics

HTML5 elements should be used where possible to reflect the semantic content of the document (See W3 Wiki).

<!-- HTML5 elements in use -->
<article>
  <header>
    <h1>Some Heading</h1>
    <p>A Subheading</p>
  </header>
  <p>Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.</p>
</article>

Remember that elements contain semantic meanings and should only be used for the correct context (see MDN). When marking up content purely for aesthetic purposes <div> and <span> are the right choice.

<!-- appropriate use of a div -->
<section>
  <div class="col-1">
    <h1>Some Heading</h1>
    <p>Sed ut perspiciatis, unde omnis iste natus error sit voluptatem accusantium doloremque laudantium.</p>
  </div>
  <div class="col-2">
    <p>Quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt, explicabo.</p>
  </div>
</section>

Style

All tags and attributes should be written in lowercase. This helps prevents bugs and is easier to read.

<!-- It's not nice to be shouted at -->
<DIV></DIV>

<!-- better -->
<div></div>

Similarly, quote style should be consistent across the document to prevent hard to track bugs. Double quotes are preferred. See Google style guide

<!-- Inconsistent -->
<img class="hero-image" src='../img/hero-image'>

<!-- Better -->
<img class="hero-image" src="../img/hero-image">

HTML should be properly indented and be consistent throughout the document. Authors are encouraged to organise content for readability, such as putting elements on one line or spacing out content.

<!-- These th elements work best on one line -->
<table>
  <tr>
    <th>Heading</th>
    <th>Heading</th>
  </tr>
</table>

<!-- Spacing out these sections helps readability and organisation -->
<section>
  <h2>Heading</h2>
  <p>Sed ut perspiciatis, unde omnis iste natus error.</p>
</section>

<section>
  <h2>Heading</h2>
  <p>Quae ab illo inventore veritatis et quasi</p>
</section>

Comments can be used to help developers navigate through the markup, although they don't need to be used on every closing tag.

<!-- This is probably overkill, any text editor will make this clear -->
<div class="outer-wrapper">
  <div class="inner-wrapper">
    <p>Quae ab illo inventore veritatis et quasi</p>
  </div><!-- end inner-wrapper -->
</div><!-- end outer-wrapper -->

<!-- This is a bit more sensible -->
<!-- Blog Posts -->
<section>
  <article>
    <h2>Heading</h2>
    <p>Sed ut perspiciatis, unde omnis iste natus error.</p>
  </article>
  <article>
    <h2>Heading</h2>
    <p>Quae ab illo inventore veritatis et quasi</p>
  </article>
</section>

Forms

All form elements should have a label, although these may be hidden in certain cases (see accessibility section).

<!-- Label for input type -->
<label for="username">Click me</label>
<input type="text" id="username">

<!-- Labels can also wrap fields instead -->
<label>Click me<input type="text"></label>

Many attributes on form elements don't require a value to be set like disabled or checked.

<input type="text" disabled>

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