Write HACKING document with coding guidelines and actually fix the

code to follow it.

1 files changed, 67 insertions, 0 deletions

diff --git a/HACKING b/HACKING
new file mode 100644
index 0000000..0d2cdfe
--- /dev/null
+++ b/HACKING
@@ -0,0 +1,67 @@
+First attempt to create coding guidelines
+-----------------------------------------
+
+1) Generally formatting style should be roughly similar to Java style
+   (similar to K&R), so that function looks like this:
+
+    function Foo (bar, baz) {
+        if (bar) {
+            console.log("bar!");
+            return baz / 2;
+        } else {
+            console.log("no bar!");
+            return baz * 2;
+        }
+    }
+
+2) Indentation is 4 spaces, no TABs
+
+3) Generally I would like to follow formatting and other advice by jslint
+   (http://www.jslint.com/). However, I don't want to be bound by sometimes
+   eccentric opinions of Douglas Crockford, more I care about checking
+   for missing semicolons, bad spacing, etc. However, in order to make
+   jslint at least partially work, I need to be quite conservative in
+   using any non-standard constructs (Douglas strictly refused to add
+   any non-standard pieces of syntax, particularly let, when I emailed
+   him about it).
+   It follows that let and other non-ECMAScript construcsts shouldn't be used
+   or at least sparingly and only in the time of dire need.
+
+4) Object literals should be used for pure data objects only. Instead of
+
+    var Foo.prototype = {
+        bar: function bar () {
+            console.log("We are in bar! Yuchuuu!!!");
+        },
+        baz: function baz () {
+            console.log("We are in baz :(");
+        }
+    };
+
+    write rather two functions separately as in
+
+    Foo.prototype.bar = function bar () {
+        console.log("We are in bar! Yay!!!");
+    };
+
+    Foo.prototype.baz = function baz () {
+        console.log("We are in baz :( Shooot.");
+    };
+
+    The latter is in my opinion more readable and works better in editors
+    I use (gedit, scribes, and eclipse).
+
+5) Use plain Javascript only. This is not multi-platform (meaning mult-browser)
+   script so no Javascript libraries (e.g., jQuery, Dojo, etc.) should be
+   used.
+   On the other hand, we don't have to bound ourselves to compatibility
+   with anything else than platforms Jetpack runs on ... which is currently
+   (for -prototype) FF 3.5 and for Jetpack-SDK it will be probably even
+   higher when it is going to be actually released. So, instead of
+   hopeless non-standard constructs of jQuery, element.querySelector (with
+   standard CSS3 selector, which is NOT the same as what's used in
+   jQuery; see http://www.w3.org/TR/2009/PR-css3-selectors-20091215/) and other
+   advanced Javascript functions can be used.
+
+Any other items could be added after discussion and when a need to decide
+some pressing issue happens.