Firebug Coding Style

From FirebugWiki

(Difference between revisions)
Jump to: navigation, search
(Example File)
(Changed code blocks to use syntax highlighting)
Line 6: Line 6:
* [https://developer.mozilla.org/en/JavaScript_Tips Mozilla JavaScript Tips]
* [https://developer.mozilla.org/en/JavaScript_Tips Mozilla JavaScript Tips]
* [https://developer.mozilla.org/En/Developer_Guide/Coding_Style Mozilla Coding Style]
* [https://developer.mozilla.org/En/Developer_Guide/Coding_Style Mozilla Coding Style]
-
 
== Formatting Code ==
== Formatting Code ==
Line 23: Line 22:
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 a XML 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 a *.properties or *.manifest 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 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 functions 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 left bracket):
-
<pre>
+
<source lang="javascript">
if (...)
if (...)
{
{
Line 83: Line 89:
{
{
}
}
-
</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 (...)
{
{
Line 100: Line 106:
     }
     }
}
}
-
</pre>
+
</source>
-
<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 115: Line 121:
{
{
}
}
-
</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:
-
<pre>
+
<source lang="javascript">
if (...)
if (...)
{
{
Line 137: Line 143:
     dump(2);
     dump(2);
}
}
-
</pre>
+
</source>
=== Horizontal Lines ===
=== Horizontal Lines ===
Line 143: Line 149:
Sometimes is helpful to divide portions of a file by a horizontal line. For this, you should use following comment (100 characters long):
Sometimes is helpful to divide portions of a file by a horizontal line. For this, you should use following comment (100 characters long):
-
<pre>// ********************************************************************************************* //</pre>
+
<source lang="javascript">
 +
// ********************************************************************************************* //
 +
</source>
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).
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).
-
<pre>   // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //</pre>
+
<source lang="javascript">
-
 
+
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 +
</source>
== Naming ==
== Naming ==
Line 155: Line 164:
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>
=== 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>
-
<pre>
+
<source lang="javascript">
MyObject.prototype = ()
MyObject.prototype = ()
{
{
Line 189: Line 198:
     }
     }
};
};
-
</pre>
+
</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;
 +
</source>
Use <code>var</code> instead of <code>const</code> since the code can be also used in browser environment where ''const'' is not supported.
Use <code>var</code> instead of <code>const</code> since the code can be also used in browser environment where ''const'' is not supported.
-
 
=== Variables ===
=== Variables ===
Variable should use camelCase and not capitalize the first letter.
Variable should use camelCase and not capitalize the first letter.
-
<pre>var thisIsMyVariable = true;</pre>
+
<source lang="javascript">
-
 
+
var thisIsMyVariable = true;
 +
</source>
=== Prefixes ===
=== Prefixes ===
Line 213: Line 224:
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 235:
     }
     }
});
});
-
</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 248:
     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 262:
{
{
}
}
-
</pre>
+
</source>
== Example File ==
== Example File ==
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.
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.
-
<pre>/* See license.txt for terms of usage */
+
<source lang="javascript">
 +
/* See license.txt for terms of usage */
FBL.ns(function() {
FBL.ns(function() {
Line 291: Line 303:
// ********************************************************************************************* //
// ********************************************************************************************* //
-
});</pre>
+
});
 +
</source>
The code should also have [http://getfirebug.com/wiki/index.php/Firebug_Source_Code_Comments comments].
The code should also have [http://getfirebug.com/wiki/index.php/Firebug_Source_Code_Comments comments].
Line 298: Line 311:
Example of a typical asynchronous module definition. Every file in Firebug source base should use AMD pattern since Firebug 1.8
Example of a typical asynchronous module definition. Every file in Firebug source base should use AMD pattern since Firebug 1.8
-
<pre>/* See license.txt for terms of usage */
+
<source lang="javascript">
 +
/* See license.txt for terms of usage */
define([
define([
Line 340: Line 354:
// ********************************************************************************************* //
// ********************************************************************************************* //
-
});</pre>
+
});
 +
</source>
The code should also have [http://getfirebug.com/wiki/index.php/Firebug_Source_Code_Comments comments].
The code should also have [http://getfirebug.com/wiki/index.php/Firebug_Source_Code_Comments comments].

Revision as of 09:03, 18 May 2011

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!

Contents

Resources

Formatting Code

Whitespace

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

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. But keep in mind long lines are hard to read (also search results are hared to read).

Indentation

Four spaces per logic level.

Licence

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

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

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

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

In case of a *.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.

var foo = { prop1: "value1" };
 
var bar = {
    prop1: "value1",
    prop2: "value2",
};

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

Firebug.MyModule = extend(Firebug.Module,
{
    initializeUI: function()
    {
    },
});
function myFunction()
{
    // ....
}

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

if (...)
{
}
else if (...)
{
}

Another example showing how to deal with spaces:

if ((a > 0) && (b > 0))
{
}
switch (...)
{
    case 1:
    {
    }
}
for (var i=0; i<10; i++)
{
}
try
{
}
catch (err)
{
}

Firebug prefers no braces if they are not necessary.

if (...)
    dump(true);
else
    dump(false);

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

if (...)
{
    dump("0");
    dump("1");
}
else
{
    dump(2);
}

Horizontal Lines

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).

    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //

Naming

Functions and Methods

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

function foo()
{
}
function myFoo()
{
}

Objects

Constructors for objects should be capitalized and use CamelCase

function ObjectConstructor()
{
}
Firebug.MyModule = extend(Firebug.Module,
{
});
MyObject.prototype = ()
{
    myMethod: function()
    {
    }
};

Constants

Constants should be capitalized as follows

var MY_CONSTANT = true;

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

Variables

Variable should use camelCase and not capitalize the first letter.

var thisIsMyVariable = true;

Prefixes

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

Good Practices

Vertical Indentation

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

Firebug.MyModule = extend(Firebug.Module,
{
    initialize: function()
    {
    },
 
    shutdown: function()
    {
    }
});

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.

initialize: function()
{
    super.initialize.apply(this, arguments);
 
    this.onMutateText = bind(this.onMutateText, this);
    this.onMutateAttr = bind(this.onMutateAttr, this);
    this.onMutateNode = bind(this.onMutateNode, this);
}

Horizontal lines should be surrounded by new lines too

function myFunc1()
{
}
 
// ********************************************************************************************* //
 
function myFunc2()
{
}

Example File

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.

/* See license.txt for terms of usage */
 
FBL.ns(function() {
 
// ********************************************************************************************* //
// Constants
 
var MY_CONSTANT = true;
 
// ********************************************************************************************* //
// Module Implementation
 
Firebug.MyModule = extend(Firebug.Module,
{
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
    // Initialization
 
    initializeUI: function()
    {
    },
 
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
    // Toolbar Actions
 
    myButtonHandler: function()
    {
    }
});
 
// ********************************************************************************************* //
// Registration
 
Firebug.registerModule(Firebug.StartButton);
 
// ********************************************************************************************* //
});

The code should also have comments.

Example Module File (AMD)

Example of a typical asynchronous module definition. Every file in Firebug source base should use AMD pattern since Firebug 1.8

/* See license.txt for terms of usage */
 
define([
    "firebug/lib",
    "firebug/firebug",
    "firebug/domplate"
],
function(FBL, Firebug, Domplate) {
 
// ********************************************************************************************* //
// Constants
 
var MY_CONSTANT = true;
 
// ********************************************************************************************* //
// Module Implementation
 
Firebug.MyModule = extend(Firebug.Module,
{
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
    // Initialization
 
    initializeUI: function()
    {
    },
 
    // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
    // Toolbar Actions
 
    myButtonHandler: function()
    {
    }
});
 
// ********************************************************************************************* //
// Registration
 
Firebug.registerModule(Firebug.MyModule);
 
return Firebug.MyModule;
 
// ********************************************************************************************* //
});

The code should also have comments.

Personal tools