Skip to content

Instantly share code, notes, and snippets.

@oobleck

oobleck/style-guides.md

Last active October 12, 2015 17:37
Show Gist options
  • Save oobleck/4062883 to your computer and use it in GitHub Desktop.
Save oobleck/4062883 to your computer and use it in GitHub Desktop.
Download ZIP
My Style Guide References
Raw
style-guides.md

Style Guides

Table of Contents

JavaScript

  1. airbnb JS guide + SublimeLinter settings. If using SublimeText(2) and the SublimeLinter plugin, you can download the settings file to enforce this style guide.
  2. Google's JavaScript Style Guide

Additions

  • Strict mode: !NEVER globally apply strict mode!

    Always add 'use strict'; either a) at the top of your functions, or b) at the top of your non-global IIFE. This way you can be sure that your code is as compliant as possible, without buggering up libraries and other chunks of code you don't have control over. More info on strict mode.

  • Use JSDoc syntax for all documentation

Exceptions

  • Variables: If assigning a value, can also use one var per line. But declare all unassigned variables with a single var.
  var $divs = $('div');
  var myString = "This is my string";
  var i, newString;

HTML/CSS

Google's CSS & HTML Style Guide

Additions

None

Exceptions

  • Entity References: always use &entity; or other encoding for special characters
  • ? Optional tags: Please close all non-self terminating tags (self-terminating tags: <br>, <hr>, <img>, etc)
  • CSS Hacks: !AVOID HACKS! Use the conditional <head> tag from h5bp, but increase the scope to include up to IE10. Use Modernizr for feature detection instead.

SASS/LESS

Whitespace

Use the same whitespace conventions as vanilla CSS.

Nesting

Nesting allows simple namespacing & greatly improved readability. Use nesting. As much as possible, avoid nesting more than 3-4 levels deep.

Variables

Use the same naming conventions as JavaScript.

Mixins & Placeholder Selectors

  • Use the same naming convention as classes & IDs from CSS.
  • Declare all required/configurable variables with !default suffix at the top of the mixin. Arguments should be given a default value wherever possible.
  @mixin roundCorners() {
    $borderRadius: 4px !default;
    @include border-radius( $borderRadius );
  }
  • For reusable (@extend-able) classes, consider using %placeholder selectors instead. More on Placeholder Selectors.

File Organization

  • Separate logical blocks of code into files. Examples: _variables.scss, _utility-classes.scss, _mixins.scss, _typography.scss, _tables.scss, etc.
  • Use Sprockets when in a Middleman project to //= require files. However, use @import for files that do not generate any output (@mixins, %classes, $variables)

Comments & Documentation

Use KSS or cssdoc syntax for documentation comments, otherwise use the same comment conventions as vanilla CSS.

Misc.

  • More info & rough style guide here
  • Use of _base.scss from Compass' Best practices document.

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment