AMD Module and Local Variable Naming Conventions

By on December 7, 2012 1:33 am

Client-Side web application development is becoming more and more robust. There are many amazing tools and technologies available for creating an immersive and interactive user experience. With the demand from users rising, the importance of creating code efficiently is paramount. When working with Dojo and other AMD compatible tools, you can easily harness the power of writing very modular source code. Two common challenges you might face when working with AMD are choosing meaningful names for your modules and determining naming conventions for local variable references to your modules.

First, let’s review some terminology for working with AMD.

Packages

Simply put, packages are collections of modules. dojo, dijit, and dgrid are examples of packages. Unlike a simple collection of modules in a directory, however, packages are ingrained with extra features that can significantly enhance module portability and ease-of-use.

There are three main package configuration options. name is the name of the package. location is the location of the package, and can either be a path relative to baseUrl or an absolute path. main is an optional parameter that defaults to “main” and is used to discover the correct module to load if someone tries to require the package itself. For example, if you were to try to require “dojo”, the actual file that would be loaded is “/dojo/main.js”.

Properly packaging your modules is important, as you want to limit the number of dependencies each package has. If you have packages that depend on all of your other packages, you will have a really hard time using your packages independently. You will also want to package your modules in a way that makes sense. For example, you would not want to put a module that has math calculations for pi in the same package with a module that has form widgets.

Modules

A module can be a class, a function, an object with properties and methods, or just a piece of code that executes when it is loaded. Modules are great because they allow you to write highly decoupled, succinct code that is extremely reusable.

The name for your module is automatically derived from its file location. If a module is located in the art/shapes.js file, then it can be referenced via the identifier art/shapes. More detailed information on the naming of modules as well as defining them and requiring them can be found in the AMD API specification.

The Dojo Loader makes relocation an easy process. If you need to reuse a module, you can simply copy its file and place it in any other directory. For example, if you move a file for your module from art/shapes.js to geometry/shapes.js, you can reference this module by its new identifier geometry/shapes. As you can see, moving modules to different packages is simple. This makes decoupling and reusing your code extremely easy.

The Dojo Loader allows you to map these modules to any local variable name that you specify. Choosing these names and how your code is packaged is one of the most crucial decisions you can make as a Dojo developer. Let’s take a couple of minutes to explore these areas in more detail and see how they can benefit your development efforts.

What Should I Name My Modules?

When developing modules, using proper naming conventions improves development efficiency, keeps your API clean, and reduces the need to remember the exact name of a module. This allows you to spend your time on more meaningful tasks, such as enhancements or bug fixes. Considerations you should look at when deciding what to name your modules are things such as, “Is this a constructor?” or “Is this a mixin?”, etc. These things can change the recommended naming conventions for your modules.

If your module is a constructor, such as a widget, it should be in an UpperCamelCase format. If it is a mixin, it should follow the _UnderscoreMixin format. If it is neither of these, it should follow the lowerCamelCase format, typically used for a singleton.

Aside from naming your modules properly, it’s also a good idea to have a standard for what variable you map your modules to when using them in a require callback. In Dojo development, this is called the “Preferred Arg Alias”, and some of these are recommended in the dojo.XX AMD modules spreadsheet. As you can see in this spreadsheet, most of the module names are concise and meaningful. Their preferred arg alias is similar, if not exact, to the module name, and the modules are packaged in a way that makes sense. We are striving to improve this, and efforts for those improvements can be seen in the 1.x to 2.0 migration document. The benefits of choosing consistent local variable names are as follows:

  • Preserve the recommended naming conventions for constructors, mixins, and singletons
  • Provide names that are easily related to the source module
  • Choosing consistent local variable names makes it easier to reuse Dojo example and tutorials

Local variable names for modules are simply references to the module included. Sometimes a module identifier does not make for an ideal local variable. For example, if the name is a common JavaScript word such as array, we recommend adding a suffix to make it arrayUtil. Or, if the module name contains a hyphen, such as dojo/dom-construct, we recommend domConstruct, which is a valid JavaScript variable. Because these variable are simply locally scoped references to the returned value of a required module dependency, you are free to name them whatever you want, but we believe that following these consistent patterns will simplify your approach to using AMD effectively.

Conclusion

Naming your modules properly, mapping them to logical argument names, and packaging them in a way that makes sense can make your code more portable and easier to maintain and understand.

If you are interested in diving into AMD in depth, SitePen provides great Dojo workshops that can help take you from a novice Dojo programmer to a Dojo master. If you’ve already got code implemented and would like assistance in migrating it to later versions of Dojo, or help rewriting or debugging it, SitePen also offers comprehensive JavaScript support.

Comments