Assembla Development

0. Attention

Prototype.js is deprecated and must not be used, all efforts to rewrite code away from Prototype.js dependency is appreciated. 

Please review JS conventions and, if possible, How we should organize and manage our JS code.

An excellent introduction to contemporary javascript can be found at: http://eloquentjavascript.net/index.html

1. Comments

We generate browsable documentation from inline comments.

A full description of the comment format used can be found at http://developer.yahoo.com/yui/yuidoc/

/**
* Description of function 
* @param paramName {paramType} description of parameter
* @return Description of what is returned
*/ 
function aFunction(paramName){
  return "documentation is important";
};

 An example of output can be found at http://www.assembla.com/code/breakout/git/node/live/master/doc/agileplanner/generator/module_agileplanner.html

2. Use parentheses(), semicolons; and braces{} when jslint wants you to.

Ultimately Code Styles are about ensuring that code looks familiar both to save on context shifts for those that have to work on the code, but also so that the eye can catch what is out of place. The code style described here is informed by http://www.jslint.com/ which can be used in most editors or as part of the build process to catch code which may have unexpected consequence or may incur excessive human processing time when reading. 

By ensuring that javascript code generally passes jslint without issues it is much easier to catch when errors or inefficiencies are inadvertently introduced.

if (bad)
  console.log('look no braces');
...

if(good){
  console.log('braces gets you popular');
}
... 

if(concise){ console.log('not too long please'); }

3. Confirm your assumptions. Check for null, undefined and NaN.

var eL = document.getElementById('idOfElement');
eL.innerHTML = "An error waiting to happen";

var eL = document.getElementById('idOfElement');
if(eL){ 
  eL.innerHTML = "Only sets the value of eL if it actually exists";
} 

3. Don't pollute! Use var obsessively.

var aFunction = function(a){
b = "This will pollute the global namespace and possibly cause errors"; 
};

var aFunction = function(a){
var b = "This will not pollute";
}; 

If possible, use an editor that supports jslint, yes it will hurt your feelings, but you will learn to love it. 

Further reading: http://github.com/aconbere/elements_of_javascript_style/blob/master/style.mkd