Organizing your JavaScript code Better

Javascript is an interesting language because it is flexible and surprisingly powerful. Once you grow up from having one static page into having a large number of pages in a dynamic web application, you need conventions on how to organize your code.

The easy part: Namespaces, modules and commenting conventions

Javascript has no explicit syntax for advanced language features such as namespaces and private variables, but these can be implemented using very simple programming patterns.

A lot has been written on the namespace and module pattern, so I will only illustrate it here.

I like to add a "placeholder" function shown below to prevent me from making errors while modifying the module (IE6 freaks out if there is a comma after the last item). This used to happen when I moved or added the methods and forgot to check whether that the commas are correct.

// create a namespace
YAHOO.namespace("myProject");
// Assign the return value of an anonymous function to the namespace

/** @namespace */
YAHOO.myProject.myModule = function () {
	/** @private */

	var myPrivateVar = "I can be accessed only from within YAHOO.myProject.myModule.";
 
	/** @private */
	var myPrivateMethod = function () {

		YAHOO.log("I can be accessed only from within YAHOO.myProject.myModule");
	}
 
        /** @scope YAHOO.myProject.myModule */
	return  {

		/** describe myPublicProperty here */
		myPublicProperty: "I'm accessible as YAHOO.myProject.myModule.myPublicProperty."
		/** describe myPublicMethod here */
		myPublicMethod: function () {

			YAHOO.log("I'm accessible as YAHOO.myProject.myModule.myPublicMethod.");
 
			//Within myProject, I can access "private" vars and methods:
			YAHOO.log(myPrivateVar);

			YAHOO.log(myPrivateMethod());
 
			//The native scope of myPublicMethod is myProject; we can
			//access public members using "this":

			YAHOO.log(this.myPublicProperty);
		},
		/**
		* A placeholder function to prevent errors due to not having a comma after the last function in the return statement for this module.
		*/

		placeholder: function () {}
};
 
}(); // the parens here cause the anonymous function to execute and return

Commenting conventions. Pick a commenting tool and stick with it. Comment the intent of the code and any gotchas as well as the expected arguments and purpose of methods.

The two main JavaScript commenting tools are: JsDoc-Toolkit (self-contained Java) and YuiDoc (Python).

File names and splitting code into files. Put all the hard-to-reuse code into its own namespace (ex. Framework. ModuleName. ModulePart.ApplicationName) in a separate file (application.js or custom.js). This way you keep the library clean of any application-specific stuff. It is often hard to avoid implementing some things in a one-off manner, so you might as well organize all the single-use stuff in its own file.

That is, if writing your own extensions to an existing framework, you will most likely have:

The hard part: structuring code for reuse, logical naming conventions

Structuring code for reuse. Encourage reuse by splitting code into configuration, implementation and customization.

myProject.myModule = function(){

// CONFIGURATION
  var config = {
    CSS:{
     classes:{

       hover:'hover',
       active:'current',
       jsEnabled:'js'

     },
     ids:{
       container:'maincontainer'
     }

    },
    timeout:2000,
    userID:'chrisheilmann'
  };

 
  // IMPLEMENTATION
  function init(){ };
  // make init and config public

  return {
    init:init,
    config:config
  };

}();
 
// CUSTOMIZATION
// This makes it possible to override stuff before calling init
module.config.CSS.ids.container = 'header';

module.config.userID = 'alanwhite';
module.init();

Naming conventions. I don't mean deciding whether or not to use camelCase, but rather how the logical organization names of variables and widgets should be done. It is reasonably simple to stop using global variables and functions to avoid name conflicts, but what is harder is to come up with a logical naming convention that allows any code to be reused anywhere.

In particular, when you create new widgets, you often need to be able to connect them to one another in some manner. Being able to identifying the type (class) and retrieve/replace data from a new widget using a standard interface takes some planning and a lot of discipline, but it makes reusing the widgets much easier.

ID and name attribute naming convention. I use "data[widgetName][recordIndex][fieldName]" for input names (because PHP will parse this into arrays automatically) and "widgetName_fieldName_recordIndex" for ID attributes (because it makes string comparisons easier).

Widget instance naming convention. I use YAHOO.ApplicationName.WidgetInstanceName for widget instances, and use WidgetInstanceName to create any related tags with IDs.

I am still looking for a good logical naming convention for widgets, but it seems this topic is not as commonly discussed. If you have any tips, please leave a comment!