Style Guide

Here are some basic rules/recommendations

Rule Number 1

For CoffeeScript, use soft-tabs; 2 spaces wide. This is important, since CoffeeScript relies on significant whitespace.

Before you start to object, see what CoffeeScript's own wiki says on the subject

And never mix tabs and soft-tabs in the same file! You will be called mean names if you do (and so will CoffeeScript's compiler, no doubt).

Rule Number 1 (yes, 1 again. Because it's just as important)

Write tests - and run them. Often.

CoffeeScript/JavaScript

Naming Conventions

Naming conventions follow standard Java conventions:

• Class names are written as UpperCamelCase nouns, e.g. SomeFancyThing and XMLParser
• Function names and variables are written as lowerCamelCase, e.g. doSomethingFancy and parse
• Constants (or pseudo-constants, since JavaScript doesn't have real constants), are written as ALL_UPPERCASE_WITH_UNDERSCORES
• Variables and namespaces are written as lowerCamelCase, e.g. config and fileCaching

Use English names for everything.

Be descriptive in naming things, but don't overdo it. JSON.parse is just as clear as JSONParserModule.parseJSONFunction.
As a corollary to the above: It's recommended you use the full name jQuery rather than $ when writing code against the jQuery library. The dollar sign is used by many other libraries, so removes any ambiguity jQuery.

General Coding Style

• Keep your code's public interface as clean as possible - don't expose helper functions and variables that are useless to the outside world (learn to love closures)

• Namespace functions and variables in objects instead of using name-prefixes. I.e. use page.dom.insert instead of pageDOMinsert. Never use both namespacing and prefixing.

• DRY: Don't repeat yourself. If you find yourself about to copy/paste code, then stop coding, slap yourself (optional but recommended), and realize you weren't thinking straight.

• Comment your code. Not just for yourself, but so someone else can figure it out too. Inline documentation is parsed by Docco, by the way, so write your documentation so it's compatible with that (i.e. use Markdown syntax).

• Use comment labels (TODO, FIXME, CHANGED) where appropriate:

    # FIXME: The code below needs fixing, because ...
    # TODO: The code below _may_ need fixing/refactoring/more work, but is low priority
    # CHANGED: Something has been changed in a way that's important for others to know about,
               e.g. deprecated functions and such
  

• Never trust JavaScript type coercion, and…

• Throw a TypeError rather than doing type coercion, when types really matter

    # Bad, unless you truly intend to do type coercion
    someFunction = (arg) ->
      arg = String(arg)
    
    # Better
    someFunction = (arg) ->
      throw new TypeError unless typeof arg is "string"
  

• Return/throw early in a function, rather than wrapping long blocks in if clauses

    # Don't do this
    someFunction = (a, b) ->
      if a > b
        # ... lots of code
      else
        false
    
    # Better!
    someFunction = (a, b) ->
      return false unless a > b
      # ... lots of code
  

• Check your code for stray calls to console.log() or (God forbid) alert()

• Since JavaScript doesn't support constants, use empty objects instead (e.g. SOME_CONSTANT = {}). Since objects are passed by reference, they can be strictly and weakly tested for equality without JS' coercion causing false positives.

CoffeeScript Style

• Avoid overly complex unless statements like unless xyz isnt false and abc? then ...

• When in doubt, use parentheses for function calls, and curly brackets around object literals (especially if it improves readability). If you're still in doubt, compile the code and check it.

• Use CoffeeScript's @ symbol - except if it's by itself. Just looks weird

    # lol, wut?
    value = this.value
    scope = @
    
    # Better
    value = @value
    scope = this
  

• For "class level" methods, use this. instead of @ to help distinguish them from instance members:

    class Monkey
      # class method
      this.create: -> new Monkey
  

• Use explicit returns, if it improves readability

    # Not good
    someFunction = (a, b) ->
      if a > b
        # ... lots of code
        # Implicit return in the middle of the function body. Easy to miss
        value1
      else
        # ... lots of code
        # Implicit return at the end. Less easy to miss, but still.
        value2
    
    # Better
    someFunction = (a, b) ->
      if a > b
        # ... lots of code
        # Explicit return; no confusion
        return value1
      else
        # ... lots of code
        # Also explicit
        return value2
  

HTML Style

• Semantics matter!
• For custom attributes, use the data- prefix to keep things valid. Don't make stuff up.
• Check your work.
• Chek UR spellign, to. The HTML is what the end-users will see.
• And again: English names for everything.

Commits

• Commit often (and remember to push).
• Commit messages should begin with a verb, e.g. "Updated …", "Fixed …", "Added …", etc.
• Use English for commit messages