michaelthorne / front-end-code-guide

The purpose of this guide is to help you write readable, maintainable and scalable code
6 stars 0 forks source link

This is a work in progress…

Front-end Code Guide

For HTML, CSS (Sass) and JavaScript.

Overview

The purpose of this guide is to help you write readable, maintainable and scalable code. It is a living document which should reviewed on an ongoing basis.

Please open an issue on GitHub if you’d like to contribute.

Table of Contents

1. General

2. Browsers

Through the practice of progressive enhancement and graceful degradation a website should render in any web browser. But the experience for each visitor will differ based on the features supported in the version of the browser in use.

Currently supported browsers:

Do websites need to look exactly the same in every browser?

No. Although your HTML should render without CSS or JavaScript – the content must be accessible and form submissions must work.

3. HTML

3.1 General

The basic structure of an HTML document:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <meta http-equiv="x-ua-compatible" content="ie=edge">
    <title>Hello, World!</title>
    <meta name="description" content="">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <link rel="apple-touch-icon" href="https://github.com/michaelthorne/front-end-code-guide/blob/master/apple-touch-icon.png">
    <link rel="stylesheet" href="https://github.com/michaelthorne/front-end-code-guide/blob/master/main.css">
</head>
<body>
    <header role="banner">

    </header>

    <main role="main">

    </main>

    <footer role="contentinfo">

    </footer>

    <script src="https://github.com/michaelthorne/front-end-code-guide/raw/master/main.js"></script>
</body>
</html>

3.2 Terminology

HTML Elements

Elements typically consist of a start and end tag, attributes and contents. The contents of an element are determined by it’s content model. Attributes and their values are not considered to be part of the contents of an element.

Example of an element: <p>This is the content of a paragraph element.</p>

A void element is an element whose content model never allows it to have contents under any circumstances. Void elements can have attributes. – W3C

Examples of void elements in HTML: <hr>, <img>, <input>, <link>, <meta>

HTML Tags

Tags are used to mark the start and end of HTML elements. Optionally, tags can have attributes.

Example of a start tag: <p>

Example of an end tag: </p>

HTML Attributes

Attributes have a name and value and are specified in the element’s start tag.

Example of an element’s attributes: <img src="https://github.com/michaelthorne/front-end-code-guide/raw/master/" alt="">

3.3 Syntax

3.4 Document Type Definition (DTD):

Include the HTML5 doctype:

<!doctype html>

Including the doctype in a document ensures that the browser makes a best-effort attempt at following the relevant specifications. – W3C

3.5 Language

Specify the language code for your HTML document:

<html lang="en">

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. – W3C

3.6 Character Encoding

Define the HTML document’s character set as utf-8:

<meta charset="utf-8">

Unicode is a universal character set, ie. a standard that defines, in one place, all the characters needed for writing the majority of living languages in use on computers. It aims to be, and to a large extent already is, a superset of all other character sets that have been encoded. – W3C

3.7 Internet Explorer Compatibility Mode

Ensure that IE uses the latest engine:

<meta http-equiv="x-ua-compatible" content="ie=edge">

The idea behind compatibility mode is to allow web sites and applications that are not designed to modern standards to continue to work while upgrades can be made, allowing end users to upgrade to the latest browser version. Designating 'IE=edge' is the best practice because it ensures Internet Explorer uses the latest engine. The most current Internet Explorer version includes the latest security updates as well as feature support. The current version is also the fastest version. – modern.IE

3.8 Attribute Order

In order to improve the general readability of code, it is recommended to place tag attributes in the following order:

This is an example of the recommended attribute order for an image:

<img src="https://github.com/michaelthorne/front-end-code-guide/raw/master/…" width="…" height="…" title="…" alt="…">

This is an example of the recommended attribute order for a form control:

<input class="…" type="…" name="…" required>

This is an example of the recommended attribute order for an anchor:

<a class="…" href="https://github.com/michaelthorne/front-end-code-guide/blob/master/…" target="…" title="…" data-attribute="…">

This is an example of the recommended attribute order for a div:

<div class="…" id="…" aria-controls="…" role="…">

3.9 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. – WHATWG

In HTML5, the following variations for setting a boolean attribute to true are valid:

autofocus
autofocus=""
autofocus="autofocus"

However, the preference is to not add a value. For example:

<input type="text" autofocus>

3.10 Semantics

Use the appropriate element when marking up your content to give it meaning on a web page. Semantic code describes the value of the content on a page, independent of it’s style.

<!-- ✗ -->
<div class="button">Submit</div>

<!-- ✓ -->
<button>Submit</button>

Have a look at the HTML5 Sectioning Element Flowchart if you get stuck.

Avoid adding superflous parent elements when writing HTML – reduce markup wherever possible.

<!-- ✗ -->
<span class="logo">
    <img src="https://github.com/michaelthorne/front-end-code-guide/raw/master/…">
</span>

<!-- ✓ -->
<img class="logo" src="https://github.com/michaelthorne/front-end-code-guide/raw/master/…">

3.11 Using WAI-ARIA in HTML

The main goal of the ARIA specification is to improve the overall accessibility of websites.

WAI-ARIA, the Accessible Rich Internet Applications Suite, defines a way to make Web content and Web applications more accessible to people with disabilities. It especially helps with dynamic content and advanced user interface controls developed with Ajax, HTML, JavaScript, and related technologies. – WAI-ARIA Overview

As per the W3C draft, using WAI-ARIA in HTML, rather use native HTML elements wherever possible as it will have the semantics and required behaviour built-in.

3.12 Validation

Use tools like the W3C Markup Validation Service or the Nu Markup Checker to validate your markup.

Reasons for validating:

Continue reading about why you should validate.

4. CSS

4.1 General

Every time you write inline styles in your markup, a front-end developer somewhere dies – whether it’s in a style tag or directly in the markup. Don’t do it. – TMWtech

This guide assumes that Sass will be used as the preprocessor to compile your CSS. The majority of the rules in this guide also apply to vanilla CSS, unless otherwise stated.

The features in Sass that we use are:

4.2 Terminology

A rule set (also called “rule”) consists of a selector followed by a declaration block:

[selector] {
    [property]: [value];
}

A selector is a chain of one or more sequences of simple selectors separated by combinators. One pseudo-element may be appended to the last sequence of simple selectors in a selector. – W3C

For example:

.foo {
    background-color: red;
    color: white;
}

A simple selector is either a type selector, universal selector, attribute selector, class selector, ID selector, or pseudo-class. – W3C

Type

h1 {

}

Universal

* {

}

Attribute

a[rel="external"] {

}

Class

.hero {

}

ID

#top {

}

Pseudo

button:focus {

}

Combinators are: whitespace, "greater-than sign" (U+003E, >), "plus sign" (U+002B, +) and "tilde" (U+007E, ~). – W3C

For example:

Descendant combinator

nav a {

}

Child combinator

ul > li {

}

Adjacent sibling

p + h2 {

}

General sibling

div ~ hr {

}

4.3 Syntax

4.4 Commenting

4.5 Naming Conventions

4.6 Declaration Order

4.7 Selectors

5. Sass

6. JavaScript

7. Linting

8. References

9. Inspiration & Credits