Return to STYLEGUIDE.txt CVS log

Up to [Repository] / kupuMPIWG / doc

Annotation of kupuMPIWG/doc/STYLEGUIDE.txt, revision 1.1.1.1

1.1       dwinter     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.