Labs/Jetpack/Reboot/Style Guide: Difference between revisions

Labs/Jetpack/Reboot/Style Guide (view source)

Revision as of 01:56, 26 January 2010

2,048 bytes added , 26 January 2010

Went to town

Adw

Confirmed users

764

edits

@@ Line 1: / Line 1: @@
-Code style bikeshedding is great, let's do it, here we go.  From {{bug|541622}}:
+Code style bikeshedding is great, let's do it, here we go.
+== Initial Discussion ==
+From {{bug|541622}}:
 <pre>
@@ Line 77: / Line 81: @@
 Note: in Mozilla code, placing the dot "member operator" at the end of the first line of a member operation that spans two lines is the newer convention that became popular during early development of Firefox, while placing it at the beginning of the next line is the older convention that was popular in Mozilla Suite code (and I think is still the convention in Seamonkey and possibly Thunderbird).
-----
+== Proposals ==
+'''These are just proposals!  Don't like?  Say so, let's git'r done.'''
+=== Style ===
+If all branches of a conditional are single-liners, no braces needed:
+<pre class="brush:js;toolbar:false;">
+if (foo)
+  bar();
+else
+  baz();
+</pre>
+If a branch requires more than one line so as not to exceed 80 columns, use braces:
+<pre class="brush:js;toolbar:false;">
+if (foo) {
+  Cc["@mozilla.org/appshell/window-mediator;1"].
+    getService(Ci.nsIWindowMediator).
+    getEnumerator("navigator:browser").
+    doSomethingOnce();
+}
+</pre>
+If any branch requires braces, use them for all:
+<pre class="brush:js;toolbar:false;">
+if (foo) {
+  Cc["@mozilla.org/appshell/window-mediator;1"].
+    getService(Ci.nsIWindowMediator).
+    getEnumerator("navigator:browser").
+    doSomethingOnce();
+}
+else {
+  baz();
+}
+</pre>
+Loops always require braces:
+<pre class="brush:js;toolbar:false;">
+for (let i = 0; i < len; i++) {
+  arr[i] = 0;
+}
+</pre>
+Do not cuddle <tt>else</tt> and <tt>catch</tt>.
+<pre class="brush:js;toolbar:false;">
+// Do this:
+if (foo) {
+  bar();
+  baz();
+}
+else {
+  qux();
+}
+// Not this:
+if (foo) {
+  bar();
+  baz();
+} else {
+  qux();
+}
+</pre>
+Dots at the end of lines, not the front:
+<pre class="brush:js;toolbar:false;">
+// Do this:
+Cc["@mozilla.org/appshell/window-mediator;1"].
+  getService(Ci.nsIWindowMediator).
+  getEnumerator("navigator:browser").
+  doSomethingOnce();
+// Not this:
+Cc["@mozilla.org/appshell/window-mediator;1"]
+  .getService(Ci.nsIWindowMediator)
+  .getEnumerator("navigator:browser")
+  .doSomethingOnce();
+</pre>
+=== Comments and Documentation ===
+This applies to in-source docs only, not nice docs meant for end users.
+Javadoc-style comments for functions (and maybe classes?).  Javadocs are conventional throughout Mozilla code.
+Other comments are C++-style.
+If a comment is a full sentence, capitalize and punctuate it.  Full sentences are preferable to fragments, but fragments are sometimes more effective.  Don't capitalize or punctuate fragments.
-Proposal to document options objects:
+Documenting function params that are options objects:
 <pre class="brush:js;toolbar:false;">