CoffeeScript

The main aim of this style-guide is to get the best possible readability (and not writability).

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Naming Conventions

• Names SHOULD be descriptive
• camelCase MUST be used for naming objects, functions, and instances
• PascalCase MUST be used for classes and constructor names

Whitespace

• Tabs MUST be used for indentation
• It's RECOMMENDED to equal the indentation of a tab to 4 spaces
• You MAY use, however, a different number while working on the code to match your style preferences. Other common numbers of spaces are 2 and 8.
• There MUST be no trailing whitespace characters
• An empty newline MUST be placed at the end of a file
• Invisibles SHOULD be displayed during coding to reduce the likelihood of whitespace mistakes
• Tabs and spaces MUST NOT be mixed

Multi-line Statements

• Lines MUST not be longer than 80 characters (counting tabs as 4 spaces)
• When a statement is too long to fit on one line, line breaks MUST occur after an operator

Commas

• Commas SHOULD be omitted were possible

   foo =
   	bar: 1
   	baz: 2

  instead of

   foo =
   	bar: 1,
   	baz: 2

  and

   fruits = [
   		apple
   		melon
   		pear
   	]

  instead of

   fruits = [
   		apple,
   		melon,
   		pear
   	]

• Inline commas MUST be followed by one space character

   colors = ['green', 'yellow', 'red']

  instead of

   colors = ['green','yellow','red']

Relational Operators

• is MUST be used over ==
• not MUST be used over !
• isnt MUST be used over !=
• or MUST be used over ||
• and MUST be used over &&

Comments

• There MUST be a space between # and the first character of the comment
• The first character of the comment MUST be uppercase
• Single line comments MUST be placed on a newline above the subject of the comment
• One empty line SHOULD be put before a single line comment
• Obscure code SHOULD be commented but not obvious things
• # FIXME: MAY be used to annotate problems
• # TODO: MAY be used to capture issues which need to get solved

Strings

• Single Quotes MUST be used for simple strings except the string contains an interpolation (e.g. "#{name}")

   test = 'foo'

  instead of

   test = "foo"

Objects

• Objects MUST be split up over several lines

   vector =
   	x: 10
   	y: 20
   	z: 30

  instead of

   vector = x: 10, y: 20, z: 30

• Shorthand assignments with braces MUST be used in single-line assignments

   test = { name }

  instead of

   test = name: name

• Objects with braces MUST be indented

   return {
   	x: 1
   	y: 2
   }

  instead of

   return {
   x: 1
   y: 2
   }

Functions

• Parentheses for an empty argument list MUST be omitted

   logTest = ->
   	console.log 'test'

  instead of

   logTest = () ->
   	console.log 'test'

• Fat arrows MUST only be used when necessary

   logTest = ->
   	console.log 'test'

  instead of

   logTest = =>
   	console.log 'test'

• Implicit returns SHOULD NOT be used

   add = (a, b) ->
   	return a + b

  instead of

   add = (a, b) -> a + b

• Function calls with more than 2 arguments SHOULD be split over several lines

   doSomething(
   	'with'
   	'those'
   	'strings'
   )

  instead of

   doSomething 'with', 'those', 'strings'

Chaining

• Method chains with more than 2 method calls MUST be wrapped and indented.

   $('#items')
   	.find('.selected')
   	.highlight()

  instead of

   $('#items').find('.selected').highlight()

• Sub-properties MUST not be wrapped

   person.address.country
   	.toUpperCase()
   	.split('')

  instead of

   person
   	.address
   	.country
   	.toUpperCase()
   	.split('')

• Methods SHOULD return @ to enable method chaining

Conditionals

• Newlines SHOULD be insterted after if and else blocks

   if isTest
   	doSomething()
   	doSomethingElse()
  
   else
   	doNothing()
   	jumpAround()

  instead of

   if isTest
   	doSomething()
   	doSomethingElse()
   else
   	doNothing()
   	jumpAround()

Type Casting

• To string: String(123)
• To number: Number('123')
• To boolean: Boolean(1)

General

You MAY (when it's absolutely necessary) differ from any rules of this guide to increase the performance. You MUST, however, explain the reasons for not sticking to a rule in a comment.

Framework specific

jQuery

• jQuery object variables MUST be prefixed with a $

   $form = $ '#myForm'

  instead of

   form = $ '#myForm'

• Lookups MUST be cached

   $form = $ '#form'
  
   $form.css {
   	'background-color': 'pink'
   }
  
   # …
  
   $form.hide()

  instead of

   $('#form').css {
   	'background-color': 'pink'
   }
  
   # …
  
   $('#form').hide()