/Coding-Standards

HTML, CSS, and JS coding standards

About

This style guide is intended to provide a place to gather my thoughts around coding standards. For now this guide is mainly focused on frontend technologies, but other disciplines and languages may be added in the future.

As ideas, best practices, and standards continue to emerge and evolve - so shall this guide. Very few things in this guide are considered "the law", and many folks will not agree with everything here. That said, I'd love to hear any feedback or recommendations that you may have.

Contents

CSS

Spacing

  • Insert a single space after : in declarations.
  • Tabs or spaces should be 4 characters in width. (I prefer tabs)
  • Ensure there is one space before the final selector and opening {
  • One selector per line
  • One css property/value pair per line

Casing

As CSS features hyphen-delimited syntax, we recommend adhering to that standard. Nowhere in CSS do you see CamelCase, camelBacked, or lower_and_underscored syntax. We think it's best to stay consistent here. Take the following example:

/* Camel backed (bad) */
#contentList { /* Using one format here */
 font-weight: bold; /* And another here */
}

/* hyphen-delimited (good) */
#content-list {
 font-weight: bold;
}

Property Values

  • For colors, use hex color codes, short-codes are fine where supported: #FFF
  • Consider bytes over the wire. It's generally less bytes to have a single padding rule, instead of padding-left and padding-right for example.
a {
    margin: 10px 0 0 10px;// Instead of margin-top and margin-left
    padding: 10px 0 10px; // Leave off unnecessary values
    color: #FFF; // Shorthand syntax 
}

Declaration Ordering

Try to follow the following order where possible. If all developers know the general area that a property may appear, productivity should be increased. The general rule of thumb is in this order:

  • Display and positioning
  • Box model
  • Background
  • Fonts and colors
  • Other
div {

    // Display attributes first
    position: absolute;
    z-index: 1;

    // Box model (outside to inside)
    margin: 0 auto;
    border: 1px solid #000;
    padding: 10px;
    width: 100px;

    // Background
    background: #FFF;

    // Colors and Typography
    font-size: 12px;
    color: #FFF;
}

HTML

Tags

  • Lowercase tag and attribute names
  • Use data- attributes where applicable
  • Avoid using custom attributes
  • Do not use inline event hooks such as onclick or onload
<div class="good-tag"></div>

<div data-sauce="bbq"></div>

Indenting

All nested tags should be indented. Avoid nesting multiple block level elements on one line.

<div>
    <b>Some indented text</b>
</div>

Doctype

Generally you want to use the HTML5 doctype.

<!DOCTYPE html>

Quotes

All HTML tag attributes should use double quotes (").

<a href="#" class="btn">My Link</a>

Self-closing Tags

This guide assumes that you are serving HTML5 content, and thus there is no need for the closing slash in self closing elements. Here are some examples of self-closing tags without the closing slash.

<br>
<hr>
<img>
<input>
<link>
<meta>

Javascript

No Semicolons

Javascript provides for automatic semicolon insertion. Learn it, and embrace it. In addition to increased productivity, it makes for cleaner code.

var foo = function() {
    return true
}

alert(foo())

Casing

  • Use CamelCase for names of classes and prototypes.
  • Use camelBacked for variables and methods.
// Demonstrating proper use of casing in Javascript 
function Car() {
}

Car.prototype.pressBrakes = function() {}

var clunker = new Car()

Variables

It's highly recommended, but not required, that all variable statements in a block be declared at the top of the block. Use a single statement where it makes sense, or logical groupings of statements otherwise.

// Not ideal, using multiple var statements
function foo() {
    var sauce = 'bbq'
    var leet = false
}

// Correct, a single var statement
function foo() {
    var sauce = 'bbq',
        leet = true,
        aligned // Align variable names where possible
}

Favor Object and Array literals instead of instantiation.

// Use the literal {} instead of new Object()
var sauce = {}

// Use the literal [] instead of new Array()
var pies = []

Braces on the same line

There are very few required rules as part of this document, but this is one of them. Due to automatic semicolon insertion, we are required to use braces on the same line as statements. Take the following example:

// Bad code
var foo = function()
{
    return
    {
        cheese: 'burger'
    }
}

Javascript will stick a big ugly semicolon right after that return statement, before the object literal. The result of calling foo() will always be undefined.

// Bad code
// What Javascript sees
var foo = function()
{
    return; // <- It just stuck this big semicolon here, wtf?
    // We never execute code beyond the return statement.
    {
        cheese: 'burger'
    }
}

Here's an example of how we should structure the function:

// Good code
var foo = function() {
    return {
        cheese: 'burger'
    }
}

Comma Style

Either leading or trailing styles of commas are fine. Work with your team to see which makes more sense and stick to one style. The leading comma style is fairly new, but gaining momenteum. Some people believe it allows for easier debugging and editing of code.

The recommendation is that you use 'blocking' to align variable names where possible.

// Trailing comma approach
var sauce = 'bbq',
    comma = 'trailing',
    aligned

// Leading comma approach
var sauce = 'bbq'
  , comma = 'trailing'
  , aligned

Anonymous Functinos

Create anonymouns functions using a urnary operator followed by a self calling function. We recommend using the bang (!) for this.

!function() {
   // Do something
}()

Comments

Well formed comments should be provided for every function and class definition. A class/function level comment should follow the format of:

/**
 * Comment should begin with a slash and 2 asterisks.
 * Parameters should follow with the following format
 * @param type description of parameter
 * @return type
 */

The double slash method of comments may be used within javascript code for information which may be useful to developers.