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

From MozillaWiki
< Labs‎ | Jetpack‎ | Reboot
Jump to navigation Jump to search
No edit summary
(Nobody pays attention to this page, so "delete" it.)
Line 1: Line 1:
== Proposals ==
#REDIRECT [[Main Page]]
 
=== Style ===
 
==== General ====
 
2-column indentation.  80-character limit for all lines.
 
Dots at the end of lines, not the front:
 
<pre class="brush:js;toolbar:false;">
// Good
Cc["@mozilla.org/appshell/window-mediator;1"].
  getService(Ci.nsIWindowMediator).
  getEnumerator("navigator:browser").
  doSomethingOnce();
 
// Bad
Cc["@mozilla.org/appshell/window-mediator;1"]
  .getService(Ci.nsIWindowMediator)
  .getEnumerator("navigator:browser")
  .doSomethingOnce();
</pre>
 
==== Conditionals ====
 
A branch follows its conditional on a new line and is indented:
 
<pre class="brush:js;toolbar:false;">
if (foo)
  bar();
</pre>
 
If all branches of a conditional are one-liner single statements, no braces needed:
 
<pre class="brush:js;toolbar:false;">
if (foo)
  bar();
else if (baz)
  doThis();
else
  qux();
</pre>
 
A single-statement branch that requires multiple lines also requires braces.  The opening brace follows the conditional on the same line:
 
<pre class="brush:js;toolbar:false;">
if (foo) {
  if (bar)
    baz();
}
 
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) {
  bar();
}
else {
  doThis();
  andThat();
}
</pre>
 
Do not cuddle <tt>else</tt>:
 
<pre class="brush:js;toolbar:false;">
// Good
if (foo) {
  bar();
  baz();
}
else {
  qux();
  qix();
}
 
// Bad
if (foo) {
  bar();
  baz();
} else {
  qux();
  qix();
}
</pre>
 
==== Loops ====
 
Conditional style also applies to loop style.
 
<pre class="brush:js;toolbar:false;">
for (let i = 0; i < arr.len; i++)
  arr[i] = 0;
 
for (let i = 0; i < arr.len; i++) {
  if (i % 2)
    arr[i] = 0;
}
</pre>
 
==== Try-Catch ====
 
Do not cuddle <tt>catch</tt>:
 
<pre class="brush:js;toolbar:false;">
// Good
try {
  bar();
}
catch (err) {
  baz();
}
 
// Bad
try {
  bar();
} catch (err) {
  baz();
}
</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.  Their purpose is to help people looking at your source; in general no one expects the Javadoc tool to actually ever be used.
 
<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.  If a comment is almost a full sentence, make it a full sentence.  Full sentences are generally preferable to fragments, but fragments are sometimes more effective.  Fragments should be very terse.  Don't capitalize or punctuate fragments.
 
It's not necessary to use any special markup when referring to identifiers.  If an identifier is an English word or may otherwise be confused, the syntax <tt>|foo|</tt> is encouraged.
 
== Initial Discussion ==
 
From {{bug|541622}}:
 
<pre>
> Looks like we are using javadoc/jsdoc style comments to document functions.
</pre>
 
Oh, meant to mention that.  I'm more concerned about documenting functions in the first place than the style we use to do it.  Javadoc is definitely widely used in Mozilla for both C++ and JS, so considering that one day other people will be maintaining this code, I think it's a good idea to use it.
 
<pre>
> I wonder if it'd be helpful to just go ahead and add the function name
> to this comment, as it'd make it easier to read and for jsdoc-esque-tools
> to parse.
</pre>
 
Personally I don't like duping the name in the comment for a couple of reasons:  It's more verbose, requiring me to read more (and Javadocs are verbose enough), and there's a danger of the name in the comment and the real name going out of sync.  Javadocs elsewhere in Mozilla don't do it FWIW.
 
<pre>
> Below, I am used to the catch being on the same line as the previous
> closing bracket before it. Is that weird?
</pre>
 
Gross.  Actually, people use both styles.  I like new lines, and the JS style guide prefers new lines for elses and I presume catches too.  We can bikeshed, but we should decide if we want to enforce a style and if so do.
 
<pre>
> Is there any way to format javadoc/jsdoc text as being in monospaced
> font? Can we borrow from Markdown here or anything? In particular when
> you mention 'str' below I wasn't sure if you were referring to the
> word "string" or a variable called "str".
</pre>
 
[http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/javadoc.html#documentationcomments Javadocs are HTML], so &lt;tt&gt;foo&lt;/tt&gt; or such would be technically correct, but in Mozilla I don't think there's generally any expectation that comments will be viewed outside of the source.  I've seen |foo|, 'foo', "foo".
 
<pre>
> Some code style guides strictly specify that developers should only use one
> form
> of commenting, C-style /* */ or C++-style //. The MDC Coding Style page doesn't
> seem to make any distinction here; what do we want to do?
</pre>
 
I only use C-style for Javadocs of functions.  C++ style for everything else.  That's consistent with Mozilla in general.
 
<pre>
> Interesting that you put the dot at the end of the same line as the
> CC[], rather than at the beginning of the call to createInstance().
> I've seen both on MDC snippets and would like to standardize on one
> or the other.
>
> >+      var stream = Cc['@mozilla.org/network/file-output-stream;1'].
> >+                    createInstance(Ci.nsIFileOutputStream);
</pre>
 
Yeah.  I picked it up from Crockford, the danger being that since JS inserts semicolons automatically there's some amount of danger in prefixing the dot, e.g., if you accidentally make a new line where there shouldn't be.  Leaving the dot at the end also lets my eyes read less.  I'd like to use indentation to indicate continuation, but I'm not always consistent, e.g.:
 
<pre>
let winEnum = Cc["@mozilla.org/appshell/window-mediator;1"].
                getService(Ci.nsIWindowMediator).
                getEnumerator("navigator:browser");
</pre>
 
Myk: IMHO, when the first character of the expression is already significantly indented from the first character of the line, indentation of subsequent lines of the expression to the same column as the first character is plenty of indentation and has the beneficial side-effect of creating a strong vertical alignment down the left hand side of the expression, which makes it easier to perceive the connectedness of its elements, i.e.:
 
<pre>
let winEnum = Cc["@mozilla.org/appshell/window-mediator;1"].
              getService(Ci.nsIWindowMediator).
              getEnumerator("navigator:browser");
</pre>
 
However, in cases where you only need to use the result once and can throw it away afterwards, and thus you don't need to assign it to a variable, it makes sense to indent to clarify that the expression spans lines, i.e.:
 
<pre>
Cc["@mozilla.org/appshell/window-mediator;1"].
  getService(Ci.nsIWindowMediator).
  getEnumerator("navigator:browser").
  doSomethingOnce();
</pre>
 
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).
 
== Further Reading ==
 
* [https://developer.mozilla.org/En/Developer_Guide/Coding_Style MDC Coding Style Guidelines]

Revision as of 21:55, 23 February 2011

Redirect to:

Retrieved from "https://wiki.mozilla.org/index.php?title=Labs/Jetpack/Reboot/Style_Guide&oldid=286591"