Client Side Code Structure and Standards – Prologue
AngularJS is a wonderful JavaScript framework which allows developers to quickly create dynamic websites while keeping a maintainable code base. It is not without its quirks, however. The fact that Angular has gained so much traction despite these quirks is a testament to just how amazing of a framework it is.
The quirks that I am referring to can generally be separated into three categories:
- Documentation
- Terminology
- Standards
As you continue reading, bear in mind that these have been my experiences with AngularJS and your experiences may differ. Also, some of the issues that I describe may now be resolved but were not at the time that this was written.
Documentation
The official documentation on AngularJS is pretty terrible if it exists at all. Often times many options are available for a specific piece of functionality (api, directive, service, etc) but only a subset are explained leaving the developer to figure out the rest themselves or ask the community. Also, there is usually only one example per piece of functionality.
Don’t get me wrong, I understand that framework architects are not necessarily good writers and I would rather them focus more on the framework itself than the documentation. Additionally, whenever a deficiency or inconsistency is found in the documentation and brought up in a public forum, the developers are quick to address it.
Terminology
One of the most confusing things about AngularJS when getting started is getting used to the terminology. It’s not that it is wrong, it’s just not the standards that are used in practice by many developers. Below is a list of terms used in Angular along with what I believe their reasoning was and the names that I would normally refer to them as:
- Angular Scope => View Specific Model – This one is not too bad. I think they were trying to kill two birds with one stone here. They were trying to create a view specific model for binding as well as a private scope to handle encapsulation (Something JavaScript does not do well on its own). The Angular team combined both concepts into one here.
- Angular Controller => View Model – I have found that often times people misunderstand the term “View Model”. A View model is a piece of code that models the view and facilitates communication between the view and other parts of an application. It includes properties that are bound to the view and handlers for UI events that occur on the view. Additionally, it is created when a view is created and destroyed when the view is destroyed. It is basically about half controller and half model. Sound familiar? This describes the Angular Controller perfectly.
- Angular Factory => Controller – When I think “Factory” I think about multiple objects being created at a time and then later destroyed. Angular “Factories” basically create a singleton object used to handle a single piece of functionality. This object never goes away. Depending upon implementation, these act a lot like standard Controller classes and nothing like what I would expect from a factory.
- Angular Resource => Service – In my mind, a resource is any external item which is pulled into the code. Generally, when I hear “resource” I think external files such as images, templates, etc. In Angular, it is a way to access data via a REST service. While this loosely fits the definition of a Resource it wouldn’t be the first name I would come up with.
Once you make the mental connection between the Angular terminology and the standard terminology it makes things a lot easier to understand. For developers new to Angular, having the terminology mapping above will help with the learning curve significantly.
Standards
Since AngularJS is so new, I’m sure they are still working out their standards. Standards can be broken into file structure, code structure, and code standards. The only real example of official standards that I can find for Angular is the seed project. While it works well for basic projects, when your project grows it quickly can get out of hand. This is where we are going to make most of our progress.
