Coding Standards

Contents

Spacing

Use soft tabs with 2-space indents and make sure your text editor trims white space. In Sublime Text, this means you should set the following in your preferences:

"tab_size": 2,
"translate_tabs_to_spaces": true,
"trim_automatic_white_space": true,

Put spaces after : in property declarations.

// Right
font-size: 12px;

// Wrong
font-size:12px;

Put spaces before and after the brackets ({ }) in rule declarations.

// Right
.element { font-size: 12px; }

// Wrong
.element {font-size:12px;}

Always put a blank line between rules unless they are nested. Nested rules go on the next line.

html { background: #fff; }

body {
  margin: auto;
  width: 50%;

  .class-name {
    padding: 20px;
    vertical-align: top;
  }
}

Coding Style

Use hex color codes #000 unless using rgba. 3-character codes are always better than the 6-character ones when possible. Also make sure to keep them all lower-case.

// Right
color: #000; // or
color: #f5f5f5;

// Wrong
color: #000000; // or
color: rgb(0,0,0); // or
color: #F5F5F5;

Use // for comment blocks (instead of /* */) so they are stripped out when compiled/minified

// Right way to comment

/* Wrong way to comment */

Declare CSS properties in alphabetical order. Mixins (except for CSS3) and variables go on top, followed by properties, then followed by any nested elements. Help Scout didn’t start this way, but as you create/edit code, please move it to this order.

.class-name {
  @import "./core/mixins";
  $variable: value;

  background: #fff;
  border-radius: $border-radius;
  font-size: 12px;

  a {
    color: $link-color;
  }
}

Use double quotes instead of single quotes whenever necessary.

// Right
font-family: "Helvetica Neue", Arial, sans-serif;

// Wrong
font-family: 'Helvetica Neue', Arial, sans-serif;

Group sections of code with a comment denoting what the section does. For comments that only apply to a rule, add the comment after the opening {.

// Header
#header {}

// Content
#content {}

// Footer
#footer {}

.class-name { // this explains what the rule does
  property: value;
}

Pixels vs. Ems

Use px for font-size and line-height, as it provides more absolute control without being susceptible to other selectors.


Performance Considerations

  1. Avoid using type or element selectors in your property declaration. Limit declarations to class/ID names only.
  2. Use direct descendant selectors whenever possible.
  3. Only use nesting when it’s needed. Keep in mind each level adds more weight to the compiled CSS.

Take this HTML, for instance:

<ul class="category-list">
  <li class="item">Category 1</li>
  <li class="item">Category 2</li>
  <li class="item">Category 3</li>
</ul>
// Right
.category-list { // class namespace only
  > .item { // use of direct descendant selector (>)
    list-style-type: disc;
  }
  a { // minimal specificity, doesn't need to be nested in the li
    color: #ff0000;
  }
}

// Wrong
ul.category-list { // using element in the declaration when it's not needed
  li { // no descendant selector, using element instead of the class
    list-style-type: disc;
    a { // unnecessary nesting
      color: #ff0000;
    }
  }
}

Nesting

As a rule of thumb, a CSS rule should never need to include more than 3 levels of nesting. If it does, do your best to get to 3 levels or less. 3+ levels should be the exception, not the rule.

Suggestion: examine your compiled CSS closely from time to time, which will expose nesting that’s gotten out of hand. If the compiled CSS doesn’t look like the CSS you would write from scratch, your Sass syntax should be adjusted.

Also, break up nested rules when readability starts to become affected or too many things are listed in one set of rules. A good rule of thumb is to break up nesting of 50+ lines.

Nested elements should be placed after properties are declared for the top level element.

Right way:

// Right
.category-list { // class namespace only
  border: 1px solid #ccc;
  margin: 0;
  > li { // use of direct descendant selector (>)
    list-style-type: disc;
  }
}

// Wrong
.category-list { // class namespace only
  > li { // use of direct descendant selector (>)
    list-style-type: disc;
  }
  border: 1px solid #ccc;
  margin: 0;
}

Naming and Capitalization

The rule with naming a class or ID is to describe what it does, not what it looks like. What it looks like will change, but what it does should be more permanant.

// Right
.category-list {
  // ...
}

// Wrong
.big-green-list {
  // ...
}

Try to be thoughtful about the name and where it applies. For instance, if the class/ID is specific to a section, it’s great to denote it. For instance, .profile-social would be better than .social-network if it’s only used in the customer profile.

Clarity over brevity

Make sure the name is clear to anyone that reads it. .cs-list is not acceptable. Yet .customer-list works quite well. Just don’t get carried away, as .customer-list-of-social-networks is far too long.

Camelcase

Camelcase is preferred for elements leveraged by javascript, which makes them easier to identify. Otherwise, words separated by hyphens are preferred.

// Right
.category-list {
  ...
}
// or
.categoryList {
  ...
}

//////

// Wrong
.categoryList {
  ...
}
// or
.categorylist {
  ...
}
// or
.category_list {
  ...
}