tomevans18/HTML Style Guide.md

## HTML Style Guide.md

      
    Raw
  

              HTML Style Guide.md
            
          
    #HTML(5) Style Guide and Coding Conventions
####Part of Kagool coding guidelines

Table of Contents


Syntax
Accessibility
Validation
Use Correct Document Type
Meta Data
Close All HTML Elements
Use Lower Case Element Names
Use Lower Case Attribute Names
Boolean Attributes
Attribute Order
Quote Attribute Values
Image Attributes
Spaces and Equal Signs
Avoid Long Code Lines
Reducing Markup
JavaScript Generated Markup
Blank Lines
Omitting <html> and <body>
Omitting <head>
HTML Comments
Loading CSS and JavaScript in HTML
Older Browsers e.g. IE8
ARIA/Accessibility


###Syntax
Be smart and future proof! A consistent use of style, makes it easier for others to understand and use your HTML.

For readability, add tab indentation for to allow others to select there tab spacing. Do not use spaces.
Nested elements should be indented once.
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.
Don’t omit optional closing tags (e.g. </li> or </body>).

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


Always keep your style smart, tidy, clean and well-formed.

###Accessibility
The website will follow the W3C (World Wide Web Consortium) guidelines for accessibility. Any code written, thus not being third party code, will be ‘single A compliant’ and where possible aim to be ‘double A compliant’ unless stated otherwise in section V. The following website must be used to carry out said checks http://validator.w3.org
###Validation
The website will follow the W3C (World Wide Web Consortium) guidelines for HTML5 validation. Any code written, thus not being third party code, will pass HTML5 validation unless stated otherwise in section V. The following website must be used to carry out said checks http://validator.w3.org
###Use Correct Document Type
Always declare the document type as HTML5 and as the first line in your document:
<!DOCTYPE html>

###Meta Data
To ensure proper interpretation, and correct search engine indexing, both the language and the character encoding should be defined as early as possible in a document:
<!DOCTYPE html>
<html lang="en-US">
<head>
  <meta charset="UTF-8">
  <title>HTML5 Syntax and Coding Style</title>
</head>

For accessibility the viewport Meta tag needs to allow scaling to provide the option of zooming in on content. An initial sale can be set but prevention of scaling delivers a poor user experience and is not correct for accessibility. Below is the recomended code:
<meta name="viewport" content="width=device-width, initial-scale=1">

The <title> element is required in HTML5. Make the title as meaningful as possible:
<title>HTML5 Syntax and Coding Style</title>

###Close All HTML Elements
In HTML5, you don't have to close all elements (for example the <p> element).
We recommend closing all HTML elements except images and inputs.
Looking bad:
<section>
  <p>This is a paragraph.
  <p>This is a paragraph.
</section>

<img src="smiley.gif" alt="Smiley face" height="42" width="42" />

<input type="submit" value="Submit" />

Looking good:
<section>
  <p>This is a paragraph.</p>
  <p>This is a paragraph.</p>
</section>

<img src="smiley.gif" alt="Smiley face" height="42" width="42">

<input type="submit" value="Submit">

###Use Lower Case Element Names
HTML5 allows mixing uppercase and lowercase letters in element names.
We recommend using lowercase element names:

Mixing uppercase and lowercase names is bad
Developers are used to use lowercase names (as in XHTML)
Lowercase look cleaner
Lowercase are easier to write

Bad:
<SECTION> 
  <p>This is a paragraph.</p>
</SECTION>

Very Bad:
<Section> 
  <p>This is a paragraph.</p>
</SECTION>

Good:
<section> 
  <p>This is a paragraph.</p>
</section>

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

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

Classes make for great reusable components, so they come first. Ids are more specific and should be used sparingly (e.g., for in-page bookmarks), so they come second.
<a class="..." id="..." data-modal="toggle" href="#">
  Example link
</a>

<input class="form-control" type="text">

<img src="..." alt="...">

###Use Lower Case Attribute Names
HTML5 allows mixing uppercase and lowercase letters in attribute names.

We recommend using lowercase attribute names:
Mixing uppercase and lowercase names is bad
Developers are used to use lowercase names (as in XHTML)
Lowercase look cleaner
Lowercase are easier to write

Looking bad:
<div CLASS="menu">

Looking good:
<div class="menu">

###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.
<input type="text" disabled>

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

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

###Quote Attribute Values
HTML5 allows attribute values without quotes but we recommend:

You use quotes
Mixing styles is never good
Quoted values are easier to read

This will not work, because the value contains spaces:
<table class=table striped>

This will work:
<table class="table striped">

###Image Attributes
Always use the alt attribute with images unless the image is purely decorative. The alt attribute is important when the image cannot be viewed.
<img src="html5.gif" alt="HTML5" style="width:128px;height:128px">

###Spaces and Equal Signs
Spaces around equal signs is legal:
<link rel = "stylesheet" href = "styles.css">

But space-less must be used as it is easier to read, and groups entities better together:
<link rel="stylesheet" href="styles.css">

###Avoid Long Code Lines
When using an HTML editor, it is inconvenient to scroll right and left to read the HTML code.
Try to avoid code lines longer than 80 characters.
###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:
Bad
<span class="avatar">
  <img src="...">
</span>

Good
<img class="avatar" src="...">

###JavaScript Generated Markup
Writing markup in a JavaScript file makes the content harder to find, harder to edit, and less performant. Avoid it whenever possible.
###Blank Lines
Do not add blank lines without a reason.
For readability, add blank lines to separate large or logical code blocks.
Do not use unnecessary blank lines and indentation. It is not necessary to use blank lines between short and related items.
Unnecessary:
<body>
    
    <h1>Famous Cities</h1>
    
    <h2>Tokyo</h2>
    
    <p>
        Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
        and the most populous metropolitan area in the world.
        It is the seat of the Japanese government and the Imperial Palace,
        and the home of the Japanese Imperial Family.
    </p>

</body>

Better:
<body>

    <h1>Famous Cities</h1>
    <h2>Tokyo</h2>
    
    <p>
        Tokyo is the capital of Japan, the center of the Greater Tokyo Area,
        and the most populous metropolitan area in the world.
        It is the seat of the Japanese government and the Imperial Palace,
        and the home of the Japanese Imperial Family.
    </p>

</body>

Table Example:
<table>
    <tr>
        <th>Name</th>
        <th>Description</th>
    </tr>
    <tr>
        <td>A</td>
        <td>Description of A</td>
    </tr>
    <tr>
        <td>B</td>
        <td>Description of B</td>
    </tr>
</table>

List Example:
<ol>
    <li>LondonA</li>
    <li>Paris</li>
    <li>Tokyo</li>
</ol>

###Omitting <html> and <body>
In the HTML5 standard, the <html> tag and the <body> tag can be omitted.
The following code will validate as HTML5:
Example
<!DOCTYPE html>
<head>
  <title>Page Title</title>
</head>

<h1>This is a heading</h1>
<p>This is a paragraph.</p>

We do not recommend omitting the <html> and <body> tags.
The <html> element is the document root. It is the recommended place for specifying the page language:
<!DOCTYPE html>
<html lang="en-US">

Declaring a language is important for accessibility applications (screen readers) and search engines.
Omitting <html> or <body> can crash DOM and XML software.
Omitting <body> can produce errors in older browsers (IE9).
###Omitting <head>
In the HTML5 standard, the <head> tag can also be omitted.
By default, browsers will add all elements before <body>, to a default <head> element.
You can reduce the complexity of HTML, by omitting the <head> tag:
Example
<!DOCTYPE html>
<html>
<title>Page Title</title>

<body>
  <h1>This is a heading</h1>
  <p>This is a paragraph.</p>
</body>

</html>


Omitting tags is unfamiliar to web developers. It needs time to be established as a guideline.

###HTML Comments
Short comments should be written on one line, with a space after :
<!-- This is a comment -->

Long comments, spanning many lines, should be written with  on separate lines – no more than 80 characters long per line:
<!-- 
This is a long comment example. This is a long comment example.
This is a long comment example. This is a long comment example.
This is a long comment example. This is a long comment example.
-->

Long comments are easier to observe, if they are indented 2 spaces.
###Loading CSS and JavaScript in HTML
Use simple syntax for loading external CSS and scripts (the type attribute is not necessary). Always use minified versions, unless the site is under development. Do not use Javascript in the document.
CSS
<link rel="stylesheet" href="style.min.css">

JS
<script src="myscript.min.js">

###Older Broswers e.g. IE8
If the projects non-functional specificatinos include older browsers such as IE8 we must provide as much native support as possible with a non javascript fist approach.
To improve the UX when JS is avalible we can use Modernizer (http://modernizr.com/) and Shiv (http://html5shiv.googlecode.com/svn/trunk/html5.js) to target and improve functionality.
###ARIA/Accessibility
This still needs to be completed.