Annotation of kupu/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.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>