Skip to content

Latest commit

 

History

History
153 lines (122 loc) · 5.33 KB

HACKING

File metadata and controls

153 lines (122 loc) · 5.33 KB
Raw

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?