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

← Older edit

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

Revision as of 01:50, 27 August 2014

2,775 bytes removed , 27 August 2014

m

Reverted edits by Adw (talk) to last revision by MykMelez

GPHemsley

canmove, Confirmed users, Bureaucrats and Sysops emeriti

960

edits

@@ Line 1: / Line 1: @@
-Code style bikeshedding is great, let's do it, here we go.
+Code style bikeshedding is great, let's do it, here we go.  From {{bug|541622}}:
-== Initial Discussion ==
-From {{bug|541622}}:
 <pre>
@@ Line 80: / Line 76: @@
 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 a branch of a conditional is a single-liner, no braces needed:
-<pre class="brush:js;toolbar:false;">
-if (foo)
-  bar();
-else if (baz) {
-  doThis();
-  andThat();
-}
-else
-  qux();
-</pre>
-If a single-liner 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>
-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.
-All exported functions should be documented Javadoc-style.  Javadocs are conventional throughout Mozilla code.
-<pre class="brush:js;toolbar:false;">
-/**
- * This function doesn't return a value.
- *
- * @param foo
- *        Does the thing with the foo.
- * @param bar
- *        Don't use this.  Ever.
- */
-function f(foo, bar) {}
-/**
- * This function returns a value.
- *
- * @param  foo
- *         Does the thing with the foo.
- * @param  bar
- *         Don't use this.  Ever.
- * @return Some value.
- */
-function g(foo, bar) {}
-</pre>
-Documenting function params that are options objects:
-<pre class="brush:js;toolbar:false;">
-/**
- * This function takes an options dictionary.  e.g.,
- * f({ foo: true, bar: "baz" });
- *
- * @param options
- *        An options dictionary.  It may define the following properties:
- *        @prop foo
- *              If true, does the thing with the foo.
- *        @prop bar
- *              Don't use this.  Ever.
- */
-function f(options) {}
-</pre>
-Non-exported functions don't need to be documented this way, but it's encouraged.
-All other comments are C++-style.  If a comment is a full sentence, capitalize and punctuate it.  Full sentences are generally preferable to fragments, but fragments are sometimes more effective.  Don't capitalize or punctuate fragments.
 == Further Reading ==
 * [https://developer.mozilla.org/En/Developer_Guide/Coding_Style MDC Coding Style Guidelines]