#summary Style guide for JavaScript code contributed to Melange
#labels Importance-Useful,Phase-Guidelines,Contents-Draft

As more Javascript code in Melange is going to be developed, here's a draft for code guidelines. These guidelines are inspired by [PythonStyleGuide] page (but adapted to JS), and from [http://javascript.crockford.com/code.html Code conventions for the Javascript Programming Language]. In this very moment our code doesn't respect them, but these are going to be strict rules when [JavascriptRefactoring] will come to an end. More infos on  _why_ these rules are important later.

As poor-written Javascript is more dangerous than as it's in other languages, we're going to use [http://www.jslint.com/ Jslint] to verify code conventions compliance. See [JavascriptRefactoring] for more information on how to use it.

More infos on how to write good Javascript code on [http://dev.opera.com/articles/view/efficient-javascript/ Efficient javascript article] and in [http://www.jslint.com/lint.html Jslint code checking rules], some [http://www.klauskomenda.com/code/javascript-programming-patterns/ useful patterns] and a great [http://www.jibbering.com/faq/faq_notes/closures.html article about closures]

= Javascript Language Rules =
1. _Private and public/privileged vars/functions_: we're going to use [http://www.klauskomenda.com/code/javascript-programming-patterns/#module Module pattern], more info in [JavascriptRefactoring] page.

2. _With statement_: Do *not* use *with* statement. If you want to provide shortcuts, just create a variable that points to the object you want to access repeatedly. See explanations on [http://yuiblog.com/blog/2006/04/11/with-statement-considered-harmful/ why with statement is harmful]

3. _Iterations_: as we've jQuery always loaded, use [http://docs.jquery.com/Utilities/jQuery.each jQuery's each() function] to iterate over objects/arrays. Do not use *for...in* loops, as they can lead to [http://yuiblog.com/blog/2006/09/26/for-in-intrigue/ potential errors]

4. _Ajax calls_: *always* use {{{?=_"+(new Date().getTime())}}} when invoking an URL to avoid caching issues

5. _Global namespace pollution_: at least *avoid* it (more infos when we come to an agreement for [JavascriptRefactoring])

= Javascript Style Rules =

1. _Semicolons_: *Always*, *not* after functions as in:

{{{

function foo() {
};

}}}

This is unnecessary. But *yes* when you're storing an anonymous function inside a variable like this:

{{{

var foo = function () {
};

}}}

2. _Line length_: *80* columns maximum. If you need to break one line, indent it by *2* spaces

3. _Indentation_: *2* spaces (*no tabs*)

4. _Whitespaces_: *no* whitespaces inside parentheses, brackets or braces

5. _HTML Django templates_: there should be *no* code in them

6. _Comments_: use [http://code.google.com/p/jsdoc-toolkit/ JSDocToolkit] style

7. _Functions_: *no space* between the _name of the function_ and the parenthesis

8. _Anonymous functions_: *1 space* between the word _function_ and the parenthesis

9. _Immediately invoked functions_: wrap them *between parenthesis*, as in:
{{{
var myvar = (function () {
  return true;
}());
}}}

10. _Objects and arrays_: use {{{ {} }}} to declare objects (not {{{new Object()}}}) and {{{[]}}} to declare arrays (not {{{new Array()}}})

11. _Variables_: always use *var*, otherwise the variable will pollute the global namespace

12. _Primitive objects_: *never* extend their prototype

13. _String concatenation_: use

{{{
var concatenated = ["string1","string2"].join("");
}}}

instead of

{{{
var concatenated = "string1" + "string2";
}}}

It's usually faster for browsers and more beautiful when new lines are needed because line is too long.

If line is too long or you're going to store HTML, than indent it like this:

{{{
var foo = [
  '<div>',
  '  <table>',
  '  </table>',
  '</div>'
].join("");
}}}

This won't break jsLint and helps understanding indentation in the HTML code as well.