[Sommaire] [Imprimer]

   1  ==========================
   2  Kupu JavaScript styleguide
   3  ==========================
   4  
   5  Small style guide for the JavaScript code.  Please adhere to this
   6  style guide whenever possible.  Of course if something isn't mentioned
   7  here that doesn't mean you can do whatever you like, try to find a
   8  similar pattern in the code and follow that, if you think it's useful
   9  to add a line about that pattern in this guide you are very welcome to
  10  do so.  If something is not mentioned here and a similar pattern can
  11  not be found in the code find a sensible solution and add the pattern
  12  here if appropriate.
  13  
  14  Some general rules:
  15  -------------------
  16  
  17  * Explicit is better than implicit ;)
  18  
  19    When writing code, try to avoid implementing magic, don't *ever*
  20    think users/integrators are stupid and need magic.  Usually adding
  21    magic means obscuring logic and removing flexibility and we would
  22    like to avoid both.
  23  
  24  * Use verbose variable names rather then short ones.
  25  
  26    Variable names like 'i' and 'n' can be used, but only in small
  27    blocks like for and while loops
  28  
  29  Some syntactical rules:
  30  -----------------------
  31  
  32  * A comma should be followed by a whitespace
  33  
  34  * Operands (+, -, = etc.) are surroned by exactly one space, e.g.::
  35  
  36      a = b + c;   instead of   a=b+c;
  37  
  38  * The body of loops should *always* be surrounded by curly braces, even
  39    if it's only a single line. A loop starts with the loop statement,
  40    then a space, then a curly brace and on the next line the body starts
  41    with indentation.
  42  
  43  * Opening parentheses are not followed by a space nor are closing
  44    preceded by one, e.g.::
  45  
  46      doSomething(some_var);   instead of   doSomething( some_var );
  47  
  48  * A closing curly brace should be followed by a semi-colon, except
  49    when used inline, e.g.::
  50  
  51      doSomething(some_var, function() {alert('foo')});
  52  
  53  * Indentation in ECMAScript should be done using four spaces, in
  54    HTML/XML markup two spaces for child elements and four spaces for
  55    attributes. *Never* use tabs.
  56  
  57  * We use UNIX line endings (no \r!).
  58  
  59  * Try (at least *try*) not to make lines more than 80 characters wide.
  60  
  61  * Short comments should be lowercase.
  62  
  63  * Each method (at least when it's public) should have a docstring, the
  64    first line of that docstring should be a brief explanation of the
  65    method, when the docstring consists of only one line the comment is
  66    closed on the same line, else the line is followed by a whiteline,
  67    the next line is indented deeper than the first one and the comment
  68    is closed a line below the last line of the comment.
  69  
  70  * Even though the original way of defining class methods was inline, we
  71    found out that there are certain problems with that, so we switched
  72    the recommended way of attachin methods to the more common notation
  73    of 'Class.prototype.method = function() {...}'. Please make sure all
  74    code you check in follows this notation, as the old notation can lead
  75    to subtle bugs in your code (for instance, attributes with an instance
  76    value are shared in instances of classes when using the old notation).
  77  
  78  * For the above mentioned reason, all objects that have attributes should
  79    have a method called 'initialize', which should be called after object
  80    instantiation from the calling code. All instance variables must be defined
  81    in that method, since if they're defined in the constructor they're,
  82    under certain circumstanced, shared by all instances of the class. 
  83  
  84  * No double newlines, classes and functions are seperated with a
  85    single white line.
  86  
  87  * Class names are camel cased starting with an upper case char,
  88    methods are also camel cased but they start with a lowercase char,
  89    variables can vary (usually depending on the type of var: an
  90    instance will usually be camel cased and a simple integer or string
  91    will usually be completely lowercase).
  92  
  93  * When writing documentation, use reStructuredText rules. Most of the
  94    kupu documentation you find is reST.