This document attempts to explain the basic styles and patterns, that are used in Firebug codebase. New code should try to conform to these standards, so that it is as easy to maintain as existing code. Of course every rule has an exception, but it's important to know the rules nonetheless!

+

This document attempts to explain the basic styles and patterns, that are used in the Firebug codebase. New code should try to conform to these standards, so that it is as easy to maintain as existing code. Of course every rule has an exception, but it's important to know the rules nonetheless!

-

== Resources ==

+

== Formatting Code ==

+

=== File Encoding ===

+

All source files should be encoded in UTF-8 without [http://en.wikipedia.org/wiki/Byte_order_mark BOM].

The incrementation and decrementation operators are not separated by spaces. So e.g. you should write <code>while(i-- > 0)</code> instead of <code>while(i --> 0)</code> to avoid misinterpretations.

-

No tabs. No whitespace at the end of a line.

+

+

=== Source File Size ===

+

A source file should avoid huge amount of code lines. Couple thousands of lines in a file is already a lot. Firebug is using [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition AMD syntax] and more smaller files (modules) is preferred.

=== Line Length ===

=== Line Length ===

-

100 characters or less. There is no exception is *.js files! In some cases this rule can be broken in *.html or *.xul files.

+

100 characters or less. There is no exception in <code>*.js</code> files! In some cases this rule can be broken in <code>*.html</code> or <code>*.xul</code> files. But keep in mind long lines are hard to read (also search results are hard to read).

+

+

When wrapping lines, operators stay at the end of a line.

+

<source lang="javascript">

+

if ((... &&

+

...) ||

+

...)

+

{

+

}

+

</source>

+

+

<source lang="javascript">

+

var string = ... +

+

...;

+

</source>

+

+

Also member operators stay at the end of the line.

+

+

<source lang="javascript">

+

var service = Cc[...].

+

getService(...);

+

</source>

=== Indentation ===

=== Indentation ===

Four spaces per logic level.

Four spaces per logic level.

-

=== Licence ===

+

=== Commands ===

+

Every command must end with a semicolon.

+

+

Variable definitions should be done separately, not comma-separated.

+

+

<source lang="javascript">

+

var foo = 1;

+

var bar = 2;

+

+

foo = someFunction();

+

</source>

+

+

=== License ===

Files should include a license note at the first line of the file:

Files should include a license note at the first line of the file:

-

<pre>

+

<source lang="javascript">

/* See license.txt for terms of usage */

/* See license.txt for terms of usage */

...

...

-

</pre>

+

</source>

-

In case of a XML files (e.g. in overlays), this must be after XML declaration, for example:

+

In case of <code>*.xml</code> files (e.g. in overlays), this must be after XML declaration, for example:

-

<pre>

+

<source lang="xml">

<?xml version="1.0"?>

<?xml version="1.0"?>

<!-- See license.txt for terms of usage -->

<!-- See license.txt for terms of usage -->

...

...

-

</pre>

+

</xml>

+

</source>

-

In case of a *.properties or *.manifest files, this must be commented using # character.

+

In case of <code>*.properties</code> or <code>*.manifest</code> files, this must be commented using # character.

-

<pre>

+

<source lang="properties">

# See license.txt for terms of usage

# See license.txt for terms of usage

...

...

-

</pre>

+

</source>

-

+

=== Control Structures ===

=== Control Structures ===

-

Existing Firebug codebase uses braces on the next line, like as follows:

+

Existing Firebug codebase uses braces on the next line like as follows:

-

<pre>function foo()

+

<source lang="javascript">

+

function foo()

{

{

// ...

// ...

-

}</pre>

+

}

+

</source>

-

Yes, there can be exceptions and K&R style can be preferred in some cases. For example, definition of a config object.

+

Yes, there can be exceptions and [http://en.wikipedia.org/wiki/The_C_Programming_Language_%28book%29 K&R] style can be preferred in some cases. For example, definition of a config object.

-

<pre>var foo = { prop1: "value1" };

+

<source lang="javascript">

+

var foo = { prop1: "value1" };

var bar = {

var bar = {

prop1: "value1",

prop1: "value1",

prop2: "value2",

prop2: "value2",

-

};</pre>

+

};

+

</source>

-

Anyway, class and functions definitions should always have the braces on the next line as follows:

+

Anyway, class and function definitions should always have the braces on the next line as follows:

-

<pre>Firebug.MyModule = extend(Firebug.Module,

+

<source lang="javascript">

+

Firebug.MyModule = extend(Firebug.Module,

{

{

initializeUI: function()

initializeUI: function()

{

{

},

},

-

});</pre>

+

});

+

</source>

-

<pre>

+

<source lang="javascript">

function myFunction()

function myFunction()

{

{

// ....

// ....

-

}</pre>

+

}

+

</source>

-

Control structures should look like as follows (also notice the spacing between a keyword and left bracket):

+

Control structures should look like as follows (also notice the spacing between a keyword and the left bracket):

-

<pre>

+

<source lang="javascript">

if (...)

if (...)

{

{

Line 82:

Line 131:

{

{

}

}

-

</pre>

+

</source>

Another example showing how to deal with spaces:

Another example showing how to deal with spaces:

-

<pre>

+

<source lang="javascript">

if ((a > 0) && (b > 0))

if ((a > 0) && (b > 0))

{

{

}

}

-

</pre>

+

</source>

-

<pre>

+

<source lang="javascript">

switch (...)

switch (...)

{

{

case 1:

case 1:

-

{

+

...

-

}

+

break;

+

+

case 2:

+

...

+

break;

+

+

default:

+

...

}

}

-

</pre>

+

</source>

+

+

Ternary expressions must be wrapped in brackets for clarity.

+

+

<source lang="javascript">

+

var variable = (condition ? true : false);

+

</source>

+

+

To avoid misunderstandings ''for'' loops are always written in their long form, i.e. loop heads like <code>for (var i = count; i--; )</code> should be avoided in favor of <code>for (var i = count-1; i>=0; i--)</code>

-

<pre>

+

<source lang="javascript">

for (var i=0; i<10; i++)

for (var i=0; i<10; i++)

{

{

}

}

-

</pre>

+

</source>

-

<pre>

+

<source lang="javascript">

try

try

{

{

Line 114:

Line 178:

{

{

}

}

-

</pre>

+

</source>

-

Firebug prefers no braces if they are not necessary.

+

Firebug prefers no braces, if they are not necessary.

-

<pre>

+

<source lang="javascript">

if (...)

if (...)

dump(true);

dump(true);

else

else

dump(false);

dump(false);

-

</pre>

+

</source>

-

But if one of the branches needs braces use them for all:

+

But if one of the branches needs braces use them for all. Also note

-

<pre>

+

<source lang="javascript">

if (...)

if (...)

{

{

Line 136:

Line 200:

dump(2);

dump(2);

}

}

-

</pre>

+

</source>

-

=== Horizontal Lines ===

+

If the head of a control structure is wrapped into several lines because it is longer than the maximum line length, also use braces, even when the block just contains one line.

+

<source lang="javascript">

+

if (...

+

...)

+

{

+

dump("0");

+

}

+

else

+

{

+

dump(2);

+

}

+

</source>

-

Sometimes is helpful to divide portions of a file by a horizontal line. For this, you should use following comment (100 characters long):

Firebug codebase also uses following horizontal separator for dividing members of one object (this separator uses indentation (4 spaces) since it's used within an object scope that is indented (100 characters long).

+

=== Comments ===

+

Multi-line as well as single line comments should always be put into their own line.

Firebug codebase also uses the following horizontal separator for dividing members of one object (this separator uses indentation (4 spaces) since it's used within an object scope that is indented (100 characters long).

American English is used for all labels and comments. That means, that you should write e.g. <code>synchronize</code> instead of <code>synchronise</code> or <code>color</code> instead of <code>colour</code>.

=== Functions and Methods ===

=== Functions and Methods ===

Functions should use camelCase but should not capitalize the first letter.

Functions should use camelCase but should not capitalize the first letter.

-

<pre>

+

<source lang="javascript">

function foo()

function foo()

{

{

}

}

-

</pre>

+

</source>

-

<pre>

+

<source lang="javascript">

function myFoo()

function myFoo()

{

{

}

}

-

</pre>

+

</source>

-

+

-

<pre>

+

-

myObject.prototype = ()

+

-

{

+

-

myMethod: function()

+

-

{

+

-

}

+

-

};

+

-

</pre>

+

=== Objects ===

=== Objects ===

-

Constructors for objects should be capitalized and use CamelCase

+

Constructors for objects should be capitalized and use CamelCase.

-

<pre>

+

<source lang="javascript">

function ObjectConstructor()

function ObjectConstructor()

{

{

}

}

-

</pre>

+

</source>

-

<pre>

+

<source lang="javascript">

Firebug.MyModule = extend(Firebug.Module,

Firebug.MyModule = extend(Firebug.Module,

{

{

});

});

-

</pre>

+

</source>

+

+

<source lang="javascript">

+

MyObject.prototype = ()

+

{

+

myMethod: function()

+

{

+

}

+

};

+

</source>

=== Constants ===

=== Constants ===

-

Constants should be capitalized as follows

+

Constants should be capitalized as follows:

-

<pre>var MY_CONSTANT = true;</pre>

+

<source lang="javascript">

-

+

var MY_CONSTANT = true;

-

Use <code>var</code> instead of <code>const</code> since the code can be also used in browser environment where ''const'' is not supported.

+

</source>

+

Use <code>var</code> instead of <code>const</code>, since the code can also be used in the browser environment where ''const'' is not supported.

=== Variables ===

=== Variables ===

-

Variable should use camelCase and not capitalize the first letter.

+

Variables should use camelCase and not capitalize the first letter.

-

+

-

<pre>var thisIsMyVariable = true;</pre>

+

+

<source lang="javascript">

+

var thisIsMyVariable = true;

+

</source>

=== Prefixes ===

=== Prefixes ===

Firebug codebase doesn't use any prefixes for member fields.

Firebug codebase doesn't use any prefixes for member fields.

-

== Good Practices ==

== Good Practices ==

=== Vertical Indentation ===

=== Vertical Indentation ===

-

Method defintions should be separated by a new line. Note the new line between ''initialize'' and ''shutdown'' methods.

+

Method defintions should be separated by a new line. Note the new line between ''initialize'' and ''shutdown'' methods.

-

<pre>

+

<source lang="javascript">

Firebug.MyModule = extend(Firebug.Module,

Firebug.MyModule = extend(Firebug.Module,

{

{

Line 224:

Line 340:

}

}

});

});

-

</pre>

+

</source>

Also portions of code logically belonging together should be separated by a new line from other code. Note the new line between ''super.initialize'' and ''this.onMutateText''.

Also portions of code logically belonging together should be separated by a new line from other code. Note the new line between ''super.initialize'' and ''this.onMutateText''.

-

<pre>

+

<source lang="javascript">

initialize: function()

initialize: function()

{

{

Line 237:

Line 353:

this.onMutateNode = bind(this.onMutateNode, this);

this.onMutateNode = bind(this.onMutateNode, this);

}

}

-

</pre>

+

</source>

Horizontal lines should be surrounded by new lines too

Horizontal lines should be surrounded by new lines too

-

<pre>

+

<source lang="javascript">

function myFunc1()

function myFunc1()

{

{

Line 251:

Line 367:

{

{

}

}

-

</pre>

+

</source>

+

+

=== Strict Mode ===

+

+

Source files should include a "use strict"; directive below the AMD imports:

+

+

<source lang="javascript">

+

/* See license.txt for terms of usage */

+

+

define([

+

"firebug/firebug",

+

"firebug/domplate"

+

],

+

function(Firebug, D) {

+

"use strict";

+

+

// ...

+

+

});

+

</source>

+

+

Note that "with" can not be used in strict mode, so any domplate template will have to include explicit "<code>D.</code>"s before each tag.

== Example File ==

== Example File ==

-

Example of a typical Firebug file implementing a module object.

+

Example of a typical Firebug file implementing a module object. Firebug namespaces (FBL.ns) are no longer the preferred way for Firebug files. See AMD below.

The code should also have [http://getfirebug.com/wiki/index.php/Firebug_Source_Code_Comments comments].

+

The code should also have [[Firebug Source Code Comments|comments]].

+

+

== Example Module File ==

+

Example of a typical [http://wiki.commonjs.org/wiki/Modules/AsynchronousDefinition asynchronous module definition (AMD)]. Every file in Firebug source base should use the AMD pattern starting from Firebug 1.8.

Revision as of 21:47, 5 February 2013

This document attempts to explain the basic styles and patterns, that are used in the Firebug codebase. New code should try to conform to these standards, so that it is as easy to maintain as existing code. Of course every rule has an exception, but it's important to know the rules nonetheless!

The incrementation and decrementation operators are not separated by spaces. So e.g. you should write while(i-- > 0) instead of while(i --> 0) to avoid misinterpretations.

Source File Size

A source file should avoid huge amount of code lines. Couple thousands of lines in a file is already a lot. Firebug is using AMD syntax and more smaller files (modules) is preferred.

Line Length

100 characters or less. There is no exception in *.js files! In some cases this rule can be broken in *.html or *.xul files. But keep in mind long lines are hard to read (also search results are hard to read).

When wrapping lines, operators stay at the end of a line.

if((... &&
...)||
...){}

var string = ... +
...;

Also member operators stay at the end of the line.

var service = Cc[...].
getService(...);

Indentation

Four spaces per logic level.

Commands

Every command must end with a semicolon.

Variable definitions should be done separately, not comma-separated.

var foo =1;var bar =2;
foo = someFunction();

License

Files should include a license note at the first line of the file:

/* See license.txt for terms of usage */
...

In case of *.xml files (e.g. in overlays), this must be after XML declaration, for example:

<?xmlversion="1.0"?><!-- See license.txt for terms of usage -->
...
</xml>

In case of *.properties or *.manifest files, this must be commented using # character.

# See license.txt for terms of usage
...

Control Structures

Existing Firebug codebase uses braces on the next line like as follows:

function foo(){// ...}

Yes, there can be exceptions and K&R style can be preferred in some cases. For example, definition of a config object.

Firebug codebase also uses the following horizontal separator for dividing members of one object (this separator uses indentation (4 spaces) since it's used within an object scope that is indented (100 characters long).