View source for SeaMonkey:MailNews:CodingStyle

Basically, the [https://developer.mozilla.org/En/Developer_Guide/Coding_Style Mozilla C++ coding style guide rules] apply. But our MailNews code has <strike>grown</strike> evolved over the years and can be rather <strike>twisted</strike> complex, thus we favour '''readability''' over brevity.
([http://en.wikipedia.org/wiki/Indent_style Wikipedia] has an interesting comparison of the most common quoting style religions.)

The following rules describe our current practice.

=== General ===
==== No whitespace crusades ====
Yes, many MailNews code is misaligned, uses tabs instead of spaces for indentation, has trailing whitespace and what not. If doing stuff in the vicinity, fine, do the clean up. But don't touch it just for arbitrary whitespace correction, this just messes up the "whodunnit" history in our repository (and you don't want to look responsible for <strike>Blake's</strike> someone else's code, do you?).

=== JavaScript ===
In general, follow the [https://developer.mozilla.org/en/JavaScript_style_guide Mozilla JavaScript rules], but take care of these exceptions:

==== Capitalize function names ====
All names should use CamelCase, not under_score_delimiters. But while variable names should begin with lowercase characters, functions (incl. member functions) should begin with an uppercase letter:
 function CallSomething(ax)
 {
   var conspiracy = ax;
   return conspiracy;
 }

==== Default bracing style is "curly braces go on their own line" ====
To enhance readability, curly braces should be aligned vertically:
 if (condition)
 {
   let x = 23;
   CallSomething(x);
 }
 else
 {
   CallSomethingElse();
 }
There are quite some (old) files in our codebase which entirely adhere to the "opening curly braces go at the end of a line" style. If you do changes there, please keep the file's coding style consistent. Mixed coding styles only makes things worse.

Empty blocks, e.g. when implementing interfaces or <tt>try</tt>ing to <tt>catch</tt> exceptions, should really be empty and can go at the end of the line if needed:
 // implement nsIFolderListener
 var folderListener =
 {
   OnItemAdded:   function(parentItem, item) {},
   OnItemRemoved: function(parentItem, item) 
   {
     try
     {
       SomethingWhichThrows();
     }
     catch (ex) {}
   }
 };

==== If one <tt>if</tt> branch needs braces, the other should have braces as well ====
 // Fine!
 if (condition)
   CallSomething(23);
 else
   CallSomethingElse();
 
 // Bad! Don't do this!
 if (condition)
 {
   let x = 23;
   CallSomething(x);
 }
 else
   CallSomethingElse();

==== No one-line <tt>if</tt> contructs ====
Almost all contemporary debuggers are line debuggers and can't break amidst a line of code:
 // Fine!
 if (condition)
   return 42;
 
 // Bad! Don't do this!
 if (condition) return 42;

==== Use let for sub-scope variables ====
The scope of variables should as small as possible. Using the <tt>let</tt> keyword, the visibility can be restricted to the current block:
 function CallSomething(ax)
 {
   var x = 23;    // global to CallSomething!
   if (x < ax)
   {
     var y = 42;  // global to CallSomething!
     let z = 666; // local to this <tt>if</tt>
     for (let i = 0; i < ax; ++i) // i is local to the for loop
       CallSomethingElse(i);
   }
 }

=== XML/XUL ===
==== Indent is two spaces per nesting level ====
 &lt;element>
   &lt;element>
     &lt;element/>
   &lt;/element>
 &lt;/element>

==== Sort XUL attributes ====
XUL attributes should come in this rough order:
 &lt;element id="menu_showMessagePane"
          label="&showMessagePaneCmd.label;"
          accesskey="&showMessagePaneCmd.accesskey;"
          key="key_toggleMessagePane"
          random_other_attributes="put 'em here!"
          oncommand="MsgToggleMessagePane(true);"/>
Especially, id should be first, label/accesskey/key should go together and handlers should be last.

==== One attribute per line when folding ====
If the XML element definition (vastly) exceeds the 80 columns limit, it should be wrapped. In this case, put each attribute onto its own line and align them vertically:
 &lt;!-- Fine! -->
 &lt;element id="menu_showMessagePane" type="checkbox"/>
 
 &lt;!-- Bad! Don't do this! -->
 &lt;element id="menu_showMessagePane" type="checkbox" random_other_attribute1="1" random_other_attribute2="1" random_other_attribute3="1"/>
 
 &lt;!-- Fine! -->
 &lt;element id="menu_showMessagePane" 
          type="checkbox" 
          random_other_attribute1="1"
          random_other_attribute2="1"
          random_other_attribute3="1"/>

=== CSS ===
No divergent rules currently.





<div style="text-align: right">''This page is maintained by [mailto:mnyromyr@tprac.de Karsten "Mnyromyr" Düsterloh].''</div>
[[category:SeaMonkey|P]]