Code Style Guide

Every developer has their own coding style. My code style is constantly changing. As I continue to learn, I adapt my style to suit current best practices.

This is a living style guide, which I intend to keep updated as the web evolves. Currently written specifically for CSS (and preprocessors - I use both LESS, & SASS).

General principals

  • Don’t try to prematurely optimize your code; keep it readable and understandable.
  • All code in any code-base should look like a single person typed it, even when many people are contributing to it.

Spacing

  • Use two spaces for new line indenting.
  • Use one selector per line in multi-selector rulesets.
  • Add a single space between the property and value, eg padding: 10px; not padding:10px;
  • Use a new line for every selector and every declaration.
  • Use one level of indentation for each declaration.
  • Include a space after each comma in comma-separated property.
  • Include a semi-colon at the end of the last declaration in a declaration block.
  • Use one empty line between closely related rule
  • Use two empty lines between entirely new sections.
  
    .class-name,
    .another-class-name {
      margin: 0 auto;
      border: 1px solid $color-var;
    }

    .class-name {
      padding: 10px 5px;
    }


    .unrelated-class {
      background: url('image/path-to-image');
    }
  

Formating

  • Use lowercase and shorthand hex values, e.g., #aaa. Unless using rgba() for alpha channel.
  • All hex values used should be declared as variables to prevent additional colours being introduced.
  • Use single quotes consistently, e.g., content: ''.
  • Avoid specifying units for zero-values, e.g., margin: 0;.
  • Use shorthand properties where you can, eg. margin: 10px 5px 0 5px;
  • Never use !important unless you are using it as utility helper. See The Importance of !important: for further use cases.
  • Don’t over qualify selectors.
  • Use js- prefix for prefixed classes for behaviors. They are not to be referenced in stylesheets.

Comments

Comments rarely hurt. If you find an answer on Stack Overflow or in a blog post, add the link to a comment so future people know what’s up. It’s good to explain the purpose of the file in a comment at the top.

  • Use // for short comments and section headings.
  • Use /**/ for longer description comment blocks for any complicated function or mixin.
  • Add comments on a new line above their subject to separate sections.
  • Keep line-length to a sensible maximum, e.g., 80 columns.
  • Use consistent text indentation.
  
    // Section Heading
    //-----------------
    .class-name {
      font-family: $base-font;
      padding: 8px;
    }

    .class-name--item {
      padding: 4px; // last el has less height for some reason
    }


    /*
    * sass function?? 
    * find out how to do *
    */
    .class-name {

    }

  

Preprocessor considerations

  • Limit nesting to 1 level deep. Reassess any nesting more than 2 levels deep. This prevents overly-specific CSS selectors.
  • Always place @extend statements on the first lines of a declaration block.
  • Where possible, group @include statements at the top of a declaration block, after any @extend statements.
  
    .class-name {
      @extend .other-rule;
      @include clearfix();
      @include box-sizing(border-box);
      // other declarations
    }
  

Naming conventions

The naming convention I have found most useful is BEM-like naming. There is a more detailed explanation MindBEMding – getting your head ’round BEM syntax by Harry Roberts.

BEM splits components classes into three groups:

  • Block: The sole root of the component.
  • Element: A component part of the Block.
  • Modifier: A variation of the Block.

Elements are defined with two underscores (__), and Modifiers are defined by two hyphens (--).

  
    .block {
      font-size: 12px;
    }

    .block__element {
      padding: 10px;
    }

    .block--modifier {
      padding: 8px;
    }
  

Media queries

Always start with mobile first, then add breakpoints within declaration blocks where needed. This keeps all styles for a specific element grouped, and things like colours can easily be changed.

All break points are to be defined in variables, then included in mixins for use eg.

  
    @mixin tablet {
      @media (min-width: #{$screen-sm}) {
        @content;
      }
    }

    @mixin desktop {
      @media (min-width: #{$screen-md}) {
        @content;
      }
    }

    @mixin desktop-large {
      @media (min-width: #{$screen-lg}) {
        @content;
      }
    }

    @mixin desktop-xlarge {
      @media (min-width: #{$screen-xl}) {
        @content;
      }
    }
  

Usage:

  
    .element {
      font-size: @mobile-font-size;
      padding: 7px 10px;

      @include @desktop {
        font-size: @desktop-font-size;
      }
    }