1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
|
= Hacking =
If you've taken to hacking Vimperator source code, we hope that you'll share
your changes. In case you do, please keep the following in mind, and we'll be
happy to accept your patches.
== Documentation ==
First of all, all new features and all user-visible changes to existing
features need to be documented. That means editing the appropriate help files
and adding a NEWS entry where appropriate. When editing the NEWS file, you
should add your change to the top of the list of changes. If your change
alters an interface (key binding, command) and is likely to cause trouble,
prefix it with 'IMPORTANT:', otherwise, place it below the other 'IMPORTANT'
entries. If you're not sure if your change merits a news entry, or if it's
important, please ask.
== Coding Style ==
In general: Just look at the existing source code!
We try to target experienced JavaScript developers who do not
necessarily need to have a good understanding of Vimperator's source
code, nor necessarily understand in-depth concepts of other
languages like Lisp or Python. Therefore, the coding style should
feel natural to any JavaScript developer. Of course, this does not
mean, you have to avoid all new JavaScript features like list
comprehension or generators. Use them, when they make sense, but
don't use them when the resulting code is hard to read.
=== The most important style issues are: ===
* Use 4 spaces to indent things, no tabs, not 2, nor 8 spaces. If you use Vim,
this should be taken care of automatically by the modeline (like the
one below).
* No trailing whitespace.
* Use " for enclosing strings instead of ', unless using ' avoids escaping of lots of "
Example: alert("foo") instead of alert('foo');
* Use // regexp literals rather than RegExp constructors, unless
you're constructing an expression on the fly, or RegExp
constructors allow you to escape less /s than the additional
escaping of special characters required by string quoting.
Good: /application\/xhtml\+xml/
Bad: RegExp("application/xhtml\\+xml")
Good: RegExp("http://(www\\.)vimperator.org/(.*)/(.*)")
Bad: /http:\/\/(www\.)vimperator.org\/(.*)\/(.*)/
* Exactly one space after if/for/while/catch etc. and after a comma, but none
after a parenthesis or after a function call:
for (pre; condition; post)
but:
alert("foo");
* Bracing is formatted as follows:
function myFunction () {
if (foo)
return bar;
else {
baz = false;
return baz;
}
}
var quux = frob("you",
{
a: 1,
b: 42,
c: {
hoopy: "frood"
}
});
When in doubt, look for similar code.
* No braces for one-line conditional statements:
Right:
if (foo)
frob();
else
unfrob();
* Prefer lambda-style functions where suitable:
Right: list.filter(function (elem) elem.good != elem.BAD);
Wrong: list.filter(function (elem) { return elem.good != elem.BAD });
Right: list.forEach(function (elem) { window.alert(elem); });
Wrong: list.forEach(function (elem) window.alert(elem));
* Anonymous function definitions should be formatted with a space after the
keyword "function". Example: function () {}, not function() {}.
* Prefer the use of let over var i.e. only use var when required.
For more details, see
https://developer.mozilla.org/en/New_in_JavaScript_1.7#Block_scope_with_let
* Reuse common local variable names E.g. "elem" is generally used for element,
"win" for windows, "func" for functions, "ret" for return values etc.
* Prefer // over /* */ comments (exceptions for big comments are usually OK)
Right: if (HACK) // TODO: remove hack
Wrong: if (HACK) /* TODO: remove hack */
* Documentation comment blocks use /** ... */ Wrap these lines at 80
characters.
* Only wrap lines if it makes the code obviously clearer. Lines longer than 132
characters should probably be broken up rather than wrapped anyway.
* Use UNIX new lines (\n), not windows (\r\n) or old Mac ones (\r)
* Use Iterators or Array#forEach to iterate over arrays. for (let i
in ary) and for each (let i in ary) include members in an
Array.prototype, which some extensions alter.
Right:
for (let [,elem] in Iterator(ary))
for (let [k, v] in Iterator(obj))
ary.forEach(function (elem) { ...
Wrong:
for each (let elem in ary)
The exceptions to this rule are for objects with __iterator__ set,
and for XML objects (see README.E4X).
* Avoid using 'new' with constructors where possible, and use [] and
{} rather than new Array/new Object.
Right:
RegExp("^" + foo + "$")
Function(code)
new Date
Wrong:
new RegExp("^" + foo + "$")
new Function(code)
Date() // Right if you want a string-representation of the date
* Don't use abbreviations for public methods
Right:
function splitString()...
let commands = ...;
let cmds = ...; // Since it's only used locally, abbreviations are ok, but so are the full names
Wrong:
function splitStr()
== Testing/Optimization ==
TODO: Add some information here about testing/validation/etc.
Information about how/when to use :regressions might be nice.
Additionally, maybe there should be some benchmark information here --
something to let a developer know what's "too" slow...? Or general
guidelines about optimization?
// vim: set ft=asciidoc fdm=marker sw=4 ts=4 et ai:
|
