Return to STYLEGUIDE.txt CVS log

Up to [Repository] / kupuMPIWG / doc

Annotation of kupuMPIWG/doc/STYLEGUIDE.txt, revision 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.