<< Back to Calendar Home Page

	THIS PAGE IS A WORKING DRAFT
	The page may be difficult to navigate, and some information on its subject might be incomplete and/or evolving rapidly. If you have any questions or ideas, please add them as a new topic on the discussion page.

This document describes the code style that is anticipated in the Sunbird and Lightning codebase. We are aware, that not every file in the CVS tree follows these rules, but this is our goal. If you change code, try to keep these guidelines in mind. We won't reject your patch if you don't follow each and every one of these guidelines, just try to follow them as far as possible.

Some scripts have been created to automate at least some of these rules. Note however as of now, no real javascript parser/lexer has been created to find out exactly how your file is structured has been created. Some rules might fail

Automatic rule scripts

• See bug 389536

Common/General

• No vim/emacs modelines in any file
• Use the license boilerplate from https://www.mozilla.org/MPL/headers/
• Avoid duplicate code: Use existing utility functions (example: base/src/calUtils.js) if possible
• Create your own utility functions if code is being used more than once. If you cannot find a utility file to place your function in, create your own. Do so sparingly.
• When adding source code to existing functions and Objects check the possibility to adapt the existing style around your new codelines "on the way". On the other hand it may sometimes be better to take over the existing coding style.

Filenames

• In general, try to give new files a similar name as the existing files. Example: in calendar/base/content, all files are prefixed with calendar-.
• If two files are related (i.e one file is XUL and the other is the main javascript file used by this XUL file), use the same name with their respective filename extension.

Themes and CSS Style

• Regarding theme files, use calendar/base/common if the CSS applies to all themes.
• If CSS starts to differ between themes, either move the file from calendar/base/common to calendar/base/__THEME__ or create a separate file with the specific changes.

Wrapping

• If possible, use 80 characters per line. More is allowed, but if you can wrap the line into two without making the code unreadable, please do so.
• When wrapping statements on a dot, put the dot into the next line (see example)
• Long conditional blocks should be wrapped on the operators, keeping the operators in the same line.
• Single line conditionals should have their body wrapped and use correct bracket placement (See bracket placement)

var myMarvelousThing = Cc["@mozilla.org/foo/bar;1"]
                       .createInstance(Ci.nsIBar);

if (someLongCondition &&
    someEvenLongerCondition &&
    (aVeryLongOrConditionPart1 ||
     aVeryLongOrConditionPart2) &&
    oneLastCondition) {
    // Foo 
}

Comments

• Comment functions in javadoc style, add a star before each line, aligned with the first star.
• Use a set of one-line comments for inline documentation

/**
 * This is a function comment
 *
 * @param aBar        What aBar does
 * @return            What the return value is
 */
function foo(aBar) {
    // This tricky statement does something that noone will understand
    // without reading this comment.
    abracadabra();
}

Whitespace rules

• No trailing whitespaces whatsoever (even on empty lines)

Blank lines

• Maximum one blank line between code
• No blank lines between two closing brackets
• No blank lines after function headers
• No blank lines at before function closing bracket
• No blank lines at end of file

Keywords and Operators

• blank after keywords: if, while, for each, for, catch, switch
• blanks around operators: = + - * / % >= <= !=
• blank after ',' separating function arguments
• blank after semicolon in for loops (i.e for (var i = 0; i < 10; i++))

Javascript Specific

Functions

• camelCase capitalization for function names
• use 'a' prefix for Arguments (i.e function foo(aArg1, aRgh2))

Javascript Objects

• Blank line after functions
• Blank line after last variable
• No blank lines required between member variables
• No blank line after last function in the object. If the object only consists of variables, no blank line after the last variable.
• Space after colon of object key name
• On one line objects, space before and after values

var obj = { value: "foo" };

There is a further example below

Javascript Arrays

• No blank after opening bracket
• Blanks after elements

Example:

var arr = [1, 2, 3];

Bracket/Label Placement

• Place opening braces on the same line as the statement (k&r style)
• Place closing braces on the same column as the opening statement
• Both brackets on the same line when using else
• break statement aligned with previous statements in a switch
• Use brackets even for one-line if statements

if (true) {
    while (condition) {
        // ...
    }
} else {
    // ...
}

if (condition) {
   // A single line
}

switch (condition) {
    case "one":
        // Code
        break;
    case "two":
        // Code
        break;
}

Indentation

• 4 space indentation
• Minimize indentation level if possible. Example:

// Bad:
if (a) {
    if (b) {
       // do something
    }
}
// Good:
if (a && b) {
    // do something
}

Javascript Objects

• One property per line
• Opening bracket on declaration line
• No anonymous functions, optionally use first letters from object name as prefix
• Member variables first, a blank line, then functions. (see also whitespace rules)
• Semicolon at end of object
• Setters should return their value (for chaining)
• Member variables to be prefixed with 'm'

var theMostCorrectObject = {
    mMoo: 5,
    mCow: 42,
    mMilk: null,

    mFarmer: null,

    get cow() {
        return this.mCow;
    },

    set cow(v) {
        return this.mCow = v;
    },

    fooFunc: function tMCO_fooFunc(aArg1, aArg2) {

    }
};

XUL/XBL

• In general, 2 Space indentation
• All rules described for javascript (including 4 Space indentation) go for CDATA blocks of javascript.
• CDATA-tags (opening and closing) should be placed on the same line as the enclosing tag (body-tag in the example).
• 80 Characters limit is relaxed here, since its often impossible to comply
• Long lines of xml tags can be wrapped on attribute names
• Avoid using XBL bindings if the same can be achieved with pure XUL in a file. Only use XBL if the binding will be used in many locations or makes the file a lot more readable.

<tag type="xml"
     id="foo"
     other="notfoo"/>

<method name="methodName">
  <body><![CDATA[
    if (true) {
        return 42;
    }
  ]]></body>
</method>

CSS

• No quotes in url()'s
• Brackets in last selector line
• Blank line between rules

calendar-binding {
    -moz-binding: url(chrome://calendar/content/calendar-binding.xml#binding);
}

C++

TBD

Build System / Makefiles

• Use spaces instead of tabs, except where needed by make (i.e target rules)
• Do not align variable definitions using spaces, one space surrounding operators only.

# Bad:
MODULE           = calbase
LIBRARY_NAME     = calbase_s
MODULE_NAME      = calBaseModule
FORCE_STATIC_LIB = 1
GRE_MODULE       = 1

# Good:
DEPTH = ../../..
topsrcdir = @top_srcdir@
srcdir = @srcdir@
VPATH = @srcdir@

• When setting many values for a variable (i.e line exceeds 80 chars), split into multiple lines and append $(NULL)

# Good:
CPPSRCS = calDateTime.cpp \
	  calDuration.cpp \
	  calPeriod.cpp \
	  calICSService.cpp \
	  calRecurrenceRule.cpp \
	  calRecurrenceDate.cpp \
	  calRecurrenceDateSet.cpp \
	  $(NULL)

# Good:
REQUIRES = xpcom js xpconnect

# Bad:
EXTRA_SCRIPTS = calAlarmService.js calAlarmMonitor.js calAttachment.js calAttendee.js calCalendarManager.js calDateTimeFormatter.js calEvent.js