Coding Style

Navigate To:
Article: Why coding style matters View Article

Why does coding style matter?
When you have a style guide, code that otherwise seems innocuous immediately raises a flag because the style isn’t followed. This is one of the most overlooked aspects of style guides: by defining what correct code looks like, we are more easily able to identify incorrect code and therefore potential bugs before they happen.

This document defines formatting and style rules for HTML and CSS. It aims at improving collaboration, code quality, and enabling supporting infrastructure. It applies to raw, working files that use HTML and CSS. Tools are free to obfuscate, minify, and compile as long as the general code quality is maintained.

A good code guide covering much of we would like to emulate is located at Code Guide for HTML and CSS

Naming Convention

Bootstrap Classes and Overrides

Familiarize with Bootstrap classnames. They should appear first in a list of classnames. Try to avoid overriding Bootstrap classes, instead override by creating a new custom class. Why? When Bootstrap updates they may change the name of their classes. It is easier to change our own custom classes.

class="btn btn-default your-custom-class"

CSS Classes

We use a minimal approach by naming just the most necessary rules. Use lower case and names can consist of different words separated by a “-” (dash).

Components use a name:
.component {…}
.component-name {…}

ID's

ID's should not contained "-" (dash). Instead use capital case.

id="componentName"

Tools to help

Don’t be afraid of using linting tools to help enforce coding style. If these tools are available in your editor as plugins, we encourage the use of them. Here are a few tools that can help keep your team on track:

HTML5 Style

A consequent use of style, makes it easier for others to understand and use your HTML. In the future, programs like XML readers, may want to read your HTML. Below are a few general principles to follow.

  • Use correct document type <!doctype html>
  • Use lowercase element names such as <div>
  • Close empty HTML elements such as <meta charset="utf-8" />
  • Use lowercase attribute names and use quotes around them <div class="menu">
  • Always use the alt attribute with images and use that to describe what the image is<img src="path/to/img" alt="describe image" />

CSS & SCSS Style

CSS Guidelines

CSS Specificity

  • Avoid using ID's for styling. If you must use an id selector (#selector) make sure that you have no more than one in your rule declaration. A rule like #header .search #quicksearch { ... } is considered harmful.
  • When modifying an existing element for a specific use, try to use specific class names. Instead of .listings-layout.bigger use rules like .listings-layout.listings-bigger. Think about ack/greping your code in the future.
  • The class names disabled, mousedown, danger, hover, selected, and active should always be namespaced by a class (button.selected is a good example).

SCSS Guidelines

Variables and Mixins

  • You should use the variables.scss file to declare colors, typography and some formatting.
  • Familiarize and utilize Bourbon Mixin Library to reduce redundancy and speed up development.

Spacing

  • Use soft-tabs with a two space indent. Spaces are the only way to guarantee code renders the same in any person’s environment.
  • Put spaces after : in property declarations.
  • Put spaces before { in rule declarations.
  • Put line breaks between rulesets.
  • When grouping selectors, keep individual selectors to a single line.
  • Place closing braces of declaration blocks on a new line.
  • Each declaration should appear on its own line for more accurate error reporting.

Formatting

  • Use hex color codes #000 unless using rgba() in raw CSS (SCSS’ rgba() function is overloaded to accept hex colors as a param, e.g., rgba(#000, .5)).
  • Use // for comment blocks (instead of /* */).
  • Avoid specifying units for zero values, e.g., margin: 0; instead of margin: 0px;.
  • Strive to limit use of shorthand declarations to instances where you must explicitly set all the available values.

Misc

As a rule of thumb, avoid unnecessary nesting in SCSS. At most, aim for three levels. If you cannot help it, step back and rethink your overall strategy (either the specificity needed, or the layout of the nesting).