Having good code structure is important to making any project successful.  In order to learn good code structure you first need to know what code structure means.  To me, it means both how you split different pieces of functionality into different files as well as how you organize the code within your files themselves.

Code structure is not something that you can usually find good examples of.  This is because unless the point of the example is to demonstrate good code structure it is usually more effective to get to the point of the functionality instead.  The example code from AngularJS is usually short and has a very limited scope making it a poor candidate for an example of code structure.  Pretty much all functionality in the examples within Angular’s documentation takes place within the controller file and this is how we originally structured our code.

angular.module('ModuleName').controller('ControllerName', 
   [ ...injected dependencies...
      function( ...injected dependencies... ){
         ...Do Stuff...
      }
   ]
);

This structure started off fine, until we needed to share properties across controllers. The solution was actually pretty simple to handle this. We simply created a SharedProperties object and injected it into each controller which needed it. We could even add SharedProperties to scope and any changes to it anywhere would show up in the view in which is was bound.

angular.module('ModuleName').controller('ControllerName', 
   [ '$scope', 'SharedProperties', ...other injected dependencies...
      function( $scope, SharedProperties, ...other injected dependencies... ){
         $scope.SharedProperties = SharedProperties;
         ...Do Stuff...
      }
   ]
);

This worked fine for a while, but as our need for adding shared properties grew, so did our SharedProperties file. Eventually, the file looked like this:

angular.module('Derby.services').service('sharedProperties', [function () {
    return {
        selectedDivisionId: 0,
        divisions: [],
        selectedDivision: null,
        raceYears: [],
        selectedRaceYear: null,
        RaceYearId: 2012,
        RaceYear: 2012,
        isUserLoggedIn: false,
        isUserAdmin: false,
        loggedInUser: null,
        collapseResources: false,
        sharedResourcesURL: "",
        imagePath: "/Derby/Apps/Shared/Assets/Images/",
        attemptingLogin: false,
        collapseChampionshipRound: false,
        drivers: {},
        divisionHeatCache: {},
        isUserLoggedInViaFacebook: false,
        facebookAccessToken: null,
        facebookUser: null,
        selectedHeat: null
    };
}]);

A loose collection of properties thrown together because we couldn’t find a better place to put them. Property files this large makes properties difficult to find, and therefore difficult to debug.

Even though the SharedProperties technique was being abused and was becoming unwieldy, that didn’t mean it was all bad. In fact, it reminded me of a similar technique used in ActionScript. The only difference was that we would create multiple files and each would hold only properties relevant to a single concept. These are known as “Model” files. This way we could inject only the properties we need and not worry about the rest. This methodology is maintainable, much cleaner, and easy to debug.

divisionModule.factory('DivisionModel',
  [
    function () {
      return {
        divisions: [],
        selectedDivision: null,
        manageDivisionInUrl: true

      }
    }
  ]
);

This file is injected and used in the same manner as SharedProperties, just only as needed.

 Next -> Client Code Structure, Part 2: Controller Files

Now that our code is split into Models and Controllers it is much easier to read, maintain, and debug. I thought that I could take it one step further, however. Once again, I pulled from my old ActionScript standards and split each file into the following sections:

• Model Files
  • Property Initialization
  • That’s all (You expected more?)
• ViewModel Files
  • Injectables
  • Inheritance
  • Scope Initialization
  • UI Event Handlers (Handles events from the view)
  • Application Event Handlers (Handles events from $rootScope)
  • General helper functions
  • Code that runs when the view is created
• Controller Files
  • Injectables
  • Application Event Handlers 
  • Result Handlers
  • Fault Handlers
  • General helper functions
  • Code that runs when the app loads

See the example below:

divisionModule.factory('DivisionController',
    [

        /**************************************
        ***
        *** Injectables
        ***
        **************************************/

        '$rootScope',
        'DivisionModel',
        'DivisionService',

        function ($rootScope, DivisionModel, DivisionService) {

            /*********************************
            ***
            *** Application Event Handlers
            ***
            *********************************/

            function divisionSelectedHandler(event, division) {
                DivisionModel.selectedDivision = division;
            }
            $rootScope.$on('divisionSelected', divisionSelectedHandler);

            /********************************
            ***
            *** Result Handlers
            ***
            ********************************/

            function getDivisionsResultHandler(result) {
                //Apply the result
                DivisionModel.divisions = result;

                $rootScope.$emit('divisionSelected', selectedDivision);
            }

            /********************************
            ***
            *** Fault Handlers
            ***
            ********************************/

            function getDivisionsFaultHandler(fault) {
                //Handle faults
            }

            /******************************
            ***
            *** Helper Methods
            ***
            ******************************/

            function getDivisions(){
                DivisionService.query(queryParams, getDivisionsResultHandler, getDivisionsFaultHandler);
            }

            /******************************
            ***
            *** Code that runs on startup
            ***
            ******************************/

            getDivisions();
        }
    ]
);

Now, if there is a problem in the application somewhere, not only do we know exactly which file to look at, we also know which section of the file to look at.

 Next -> Client File Structure

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.

 Next -> Client Code Structure, Part 1 – Organization