HACKING

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