Code Guide

This page discusses coding guidelines and best practices used in the UI.

Jump to section

• HTML
• CSS
• JavaScript
• ReactJS

HTML

Back to top TBD

CSS

Back to top

Syntax

• All CSS selectors must be lowercase and follow the kebab casing pattern (words seperated by dashes). e.g. .selector-name instead of .selectorName
• Every selector should be followed by a space before the {. e.g. .selector { instead of .selector{
• Class names should be as short and succint as possible while remaining descriptive. e.g. .btn is short but understandble. .b is not.
• If a declaration has multiple selectors, place each selector on a newline

/* Without newlines */
.selector, .selector-two {
  ...
}

/* With newlines */
.selector,
.selector-two {
  ...
}

• Use class names instead of generic element tags. e.g. > .span-element instead of > span
• In each property declaration, include a space after the :
• All property declarations end with a semi-colon. Even though the semi-colon is optional for the last property, not including it increases the chances for errors.
• Lowercase all hex values. e.g. #fff instead of #FFF
• Whenever possible, use shorthand hex values. e.g. #fff instead of #ffffff
• Omit units for zero values. e.g. 0 instead of 0px
• Use quotes when specifying selector values, e.g.input[type="text"]
• The opening { for a rule should always be placed on the same line as the selector associated with the rule.

/* Incorrect */
.selector 
{
  ...
}

/* Correct */
.selector {
  ...
}

Shorthand notation

• Try to avoid using shorthand notation if you are not explicitly using all the properties. If you are using all the properties, use the shorthand. Be as specific as possible while remaining succinct.

/* Incorrect */
.selector {
  padding: 0 0 5px;
}

/* Correct */
.selector {
  padding-bottom: 5px;
}

Single vs. Multiple Declarations

• If a rule has only one declaration, place the entire rule on a single line. For two or more declarations per rule, place each declaration on its own line.
• In a block with multiple property declarations, always place the } on a new line.

/* Single declaration */
.selector { paddng: 10px; }

/* Multiple declarations */
.different-selector {
  display: block;
  background-color: #385d99;
}

SCSS

• Avoid unnecessary nesting. The goal is avoid redundancy.

/* Without nesting */
.component-container > .nav > .title { ... }
.component-container > .nav > .actions { ... }

/* With nesting */
.component-container > .nav {
  > .title { ... }
  > .actions { ... }
}

• Place a newline after each closing } and before each new rule.

/* Without newlines */
.selector {
  padding: 10px;
  color: red;
  .child {
    ...
  }
}

/* With newlines */
.selector {
  padding: 10px;
  color: red;
  
  .child {
    ...
  }
  
}

Comments

Comments are highly encouraged. Make sure your comments are descriptive and understandable rather than simple restatements of class names.

/* Bad comment */
/* Navigation header class */
.nav-header { ... }

/* Good comment */
/* Container element for .nav-title and .nav-actions */
.nav-header { ... }

JavaScript

Back to top

Comments

• Comments should start with a capital letter and strive to be sentences.
• Add JSDoc documentation to your classes and methods as much as is reasonable.

ReactJS

Back to top

Commenting

• ReactJS comments follow the same commenting guidelines as the JavaScript guidelines
• For each component, comment the accepted props for that component in the JSDoc for that component.

/**
 * A component that creates a label
 *
 * Props:
 *    text: The label text
 */
class Label extends Component {
    render() {
        <span className="label">{this.props.text}</span>
    }
}