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