From AlfrescoWiki

DRAFT/WIP

Contents 1 Comments 2 Functions 2.1 Callback functions 2.2 Overridable Functions 3 Constants 4 Tabs and Spaces 5 Indentation and Braces { } 6 JavaScript Features

[edit] Comments

• Comments outside functions should use the C syntax, not the C++ syntax.

/* This is the recommended comment format outside a function block. */

Multi-line comments should be aligned with existing indentation and each line should start with an asterisk.

/**
 * This is a multi-line comment.
 * Note the alignment of the asterisks.
 */

• Comments inside function blocks can be of either comment style.

/* Should use this commenting style because this is not within a function. */
function foo()
{
   // Valid comment format within a function block.
}

[edit] Functions

• Function names are defined in camelCase.
• Private functions are prefixed with an _underscore.
• Event handler functions should be prefixed with the word on.
• Function braces go on the line following the function name.

function myFunction(one, two)
{
   ...
}

• Inline functions should be named to aid debugging. Inline function names are not referenced in code.

var MyObj =
{
   myFunction: function MyObj_myFunction(one, two)
   {
      ...
   }
}

MyObj.myFunction(123, 456);

• Functions to be prefixed with header block consisting of the following parts:
  • Function description can include <pre> tags for sample code.
  • @method functionName
  • @static (if the function is defined as static)
  • @param paramName {type} description
  • @return {type} description
  • @private (if the function is private)

/**
 * Adds three numbers together and returns sum.
 * <pre>
 * addNumbers(1, 2, 3);
 * </pre>
 * @method addNumbers
 * @param one {int} the first number to be added
 * @param two {int} the second number in the addition
 * @param three {int} the third number used in the sum
 * @return {int} the sum of parameters one, two and three
 */
addNumbers: function Util_addNumbers(one, two, three)
{
   return (one + two + three);
}

[edit] Callback functions

• Common structure for specifying optional callback functions

myCallback =
{
   fn: function MyCallback(obj)
   {
      ...
   },
   obj: myArbitraryObject,
   scope: this
}

• Modules which support callbacks can either pre-define an empty function, and/or perform type checking before attempting the call

callbackFunction1 = null,

callbackFunction2 =
{
   fn: function(obj){},
   obj: null,
   scope: this
}

...

if (callbackFunction1 && (typeof callbackFunction1.fn == "function")
{
   callbackFunction1.fn.call(callbackFunction1.scope ? callbackFunction1.scope : this, callbackFunction1.obj);
}

callbackFunction2.fn.call(callbackFunction2.scope, callbackFunction2.obj);

[edit] Overridable Functions

• Note the callbackFunction2 pattern in the example above can also be used for overridable abstract functions. In this case, the function should start with "do". e.g. doBeforeFormSubmit.
• A more useful overridable function pattern expects a returned parameter, e.g. when processing a data block or optionally halting further progress.

doBeforeSubmission =
{
   fn: function(dataObj, obj)
   {
      return dataObj;
   },
   obj: null,
   scope: this
}

...

var dataObj = { ... some data ... };
dataObj = doBeforeSubmission.fn.call(doBeforeSubmission.scope, dataObj, doBeforeSubmission.obj);

[edit] Constants

• Constants should be defined in ALL_CAPS.

[edit] Tabs and Spaces

• Tab characters should not be used in source files.
• Indentations are 3 spaces per nesting level.
• Line lengths should be shorter than 80 characters where possible.
• Do not use spaces between a function and it's parameter list.
• Do use a space after a comma.

var total = addNumbers(1, 2, 3);

• Use a space between keywords and parentheses

if (condition)
{
   ...
}

[edit] Indentation and Braces { }

• Braces must be used around all if, do, switch, etc. statements
• Braces should appear on their own line.

if (some condition)
{
   ...
}
else
{
   ...
}

• Do not put compound statements on one line

if (condition) return;     /* DO NOT USE */

if (condition)             /* OK */
{
   return;
}

• NOTE the special format require when returning an object

return               /* DO NOT USE */
{
   param1: "foo",
   param2: "bar"
}

return {             /* BETTER */
   param1: "foo",
   param2: "bar"
}

return (             /* PREFERRED */
{
   param1: "foo",
   param2: "bar"
});

[edit] JavaScript Features

• Use strict equality testing where possible, must be used when testing for null
  • This is because != and == perform type coercion, which may or may not be intended.

if (x === null)
{
   ...
}

if (y !== null)
{
   ...
}

• Do not assign variables in if statements

if (a = b)           /* INTENTIONAL ASSIGNMENT, OR BUG? */

• Create arrays with []s rather than new Array(length)
• Create objects with {}s rather than new Object()
• Don't compare booleans to true or false

if (Service.isAvailable)