==========================
Kupu JavaScript styleguide
==========================

Small style guide for the JavaScript code.  Please adhere to this
style guide whenever possible.  Of course if something isn't mentioned
here that doesn't mean you can do whatever you like, try to find a
similar pattern in the code and follow that, if you think it's useful
to add a line about that pattern in this guide you are very welcome to
do so.  If something is not mentioned here and a similar pattern can
not be found in the code find a sensible solution and add the pattern
here if appropriate.

Some general rules:
-------------------

o Explicit is better than implicit ;)

  When writing code, try to avoid implementing magic, don't *ever*
  think users/integrators are stupid and need magic.  Usually adding
  magic means obscuring logic and removing flexibility and we would
  like to avoid both.

o Use verbose variable names rather then short ones.

  Variable names like 'i' and 'n' can be used, but only in small
  blocks like for and while loops

Some syntactical rules:
-----------------------

o A comma should be followed by a whitespace

o Operands (+, -, = etc.) are surroned by exactly one space, e.g.::

    a = b + c;   instead of   a=b+c;

o Opening parentheses are not followed by a space nor are closing
  preceded by one, e.g.::

    doSomething(some_var);   instead of   doSomething( some_var );

o A closing curly brace should be followed by a semi-colon, except
  when used inline, e.g.::

    doSomething(some_var, function() {alert('foo')});

o Indentation in ECMAScript should be done using four spaces, in
  HTML/XML markup two spaces for child elements and four spaces for
  attributes. *Never* use tabs.

o We use UNIX line endings (no \r!).

o Try (at least *try*) not to make lines more than 80 characters wide.

o Short comments should be lowercase.

o Each method (at least when it's public) should have a docstring, the
  first line of that docstring should be a brief explanation of the
  method, when the docstring consists of only one line the comment is
  closed on the same line, else the line is followed by a whiteline,
  the next line is indented deeper than the first one and the comment
  is closed a line below the last line of the comment.

o Class methods are defined inline like in Python instead of defining
  them on the prototype attribute (which is more common in JavaScript
  but a bit less flexible), although using the prototype attribute is
  'allowed' in extensions.

o No double newlines, classes and functions are seperated with a
  single white line.

o Class names are camel cased starting with an upper case char,
  methods are also camel cased but they start with a lowercase char,
  variables can vary (usually depending on the type of var: an
  instance will usually be camel cased and a simple integer or string
  will usually be completely lowercase).

o When writing documentation, use reStructuredText rules. Most of the
  kupu documentation you find is reST.
