AngularJS: Code Guidelines

Here is a common guidelines I use at most projects with Angular.js.

Contents:

Components

  1. Use well-defined and agreed upon component names.
    See the list of possible names in my article.

  2. No component name postfix in directives, models,filter definitions.

    You do not want to write user-directive in your templates, do you? Still you can have name collisions between directives, models and filters. I would suggest you to come with your own naming convention for this case.

  3. CamelCase in definition names.

    //correct:     
    angular.directive('user', ...);
    angular.directive('tileList', ...); 
    
    
    //incorrect:     
    angular.directive('userDirective', ...);
    angular.directive('tileListDirective', ...);
    angular.directive('tile_list', ...); 
    angular.directive('tile_list_directive', ...);
    
  4. Lower-case names for singletons and instances
    All directives, templates, services

  5. Upper-case names for Classes and creational patterns
    Classes, factories, everything returning new instance on invocation

    angular.directive('user', 
      function(
        UserModel, 
        regService, 
        ValidationService){
          return {
            link: function(){
              //UserModel must be created
              var user = new UserModel();
              //regService is a singleton
              regService.register(user);
              // ValidationService must be created
              var validation = new ValidationService();
              ...
            }
          };
    };
    

Files And File Names

  1. Single file per module/component.

  2. In general, file name must match component name.
    Exceptions directives, models, see Components rule#2

  3. Add component name postfix to directives, models and templates file names:

    // userDirective.js
    angular.directive('user', ...);
    
    
    <!-- userTemplate.html -->
    <div class="user">
        ...
    </div> 
    
    
    // UserModel.js
    angular.factory('User', ...) 
    
  4. CamelCase in file names.
    Note: there may be problems if your team members use different OS'es with both case-sensitive and case-insensitive file systems

    // installAppService.js
    angular.service('installAppService', ...)
    
  5. File names must be unique without regards to case,
    We cannot have userDirective.js and UserDirective.js simultaneously.

Prefixes

  1. Use project-specific prefixes in component and file names only if:
    1. You are sure that the project will grow (both in complexity and in number of developers).
    2. You are making a reusable plugin/component.

If you are using prefixes, then stick to this rules:

  1. Use prefixes for all components in the project.
    You cannot have prj_user.js and someDirective.js simultaneously. The correct name is prj_someDirective.js

  2. All modules must have a prefix:

    angular.module('prj_myModule',[]);
    
  3. The prefix is separated from the component name with a _ (underscore) character.

    // prj_userController.js
    angular.controller('prj_userController', ...)
    
  4. Prefix in directive definition is not separated from directive name, but is separated in file name:

    Note: This rule is derived from the necessity to have camelCase in directive names. Meanwhile, we need to support the consistency in file names, hence the exception.

    // prj_userDirective.js
    module.directive('prjUserDirective', ...)