Angular Style Guide

Angular風格指南 by @john_papa

If you are looking for an opinionated style guide for syntax, conventions, and structuring Angular applications, then step right in. These styles are based on my development experience with Angular, presentations, Pluralsight training courses and working in teams.

如果你在尋找一份關於Angular app的語法、格式以及結構的風格指南的話，那就接著看下去吧。這份風格指南是基於我在Angular上的開發經驗、一些關於這方面的演講、Pluralsight training courses以及在團隊中工作的心得而寫成。

The purpose of this style guide is to provide guidance on building Angular applications by showing the conventions I use and, more importantly, why I choose them.

這份風格指南的目的是在你建立Angular app的過程中提供一些幫助；我會在裡面展示一些我常用的方法，當然更重要的是，為什麼我會這樣做。

If you like this guide, check out my Angular Patterns: Clean Code course at Pluralsight which is a companion to this guide.
如果你喜歡這份指南，可以參考我在Pluralsight上開的課程Angular Patterns: Clean Code，他會是這份指南的好夥伴。

Community Awesomeness and Credit

Never work in a vacuum. I find that the Angular community is an incredible group who are passionate about sharing experiences. As such, a friend and Angular expert Todd Motto and I have collaborated on many styles and conventions. We agree on most, and some we diverge. I encourage you to check out Todd’s guidelines to get a sense for his approach and how it compares.

永遠不要閉門造車。我發現Angular社群是一個充滿熱情且樂於分享經驗的地方。因此，我和的朋友-Angular專家Todd Motto在許多風格和規範上合作過。大部份的時候我們的看法是相同的，不過在某些地方仍有所岐異。
我鼓勵你參考Todd’s guidelines並且感受兩者間的差異。

Many of my styles have been from the many pair programming sessions Ward Bell and I have had. My friend Ward has certainly helped influence the ultimate evolution of this guide.

我很多的風格來自於跟Ward Bell結對編程（pair programming）的過程中，這位好友對於這篇指南的幫助很大。

See the Styles in a Sample App

While this guide explains the what, why and how, I find it helpful to see them in practice. This guide is accompanied by a sample application that follows these styles and patterns. You can find the sample application (named modular) here in the modular folder. Feel free to grab it, clone it, or fork it. Instructions on running it are in its readme.

雖然這份指南會解釋what、why以及how，不過我發現在實例中使用它們會更有幫助。這份指南伴隨著這個範例app（modular），
歡迎grab、clone或fork他。

Translations

Translations of this Angular style guide are maintained by the community and can be found here.

這份指南的翻譯版本是由社群來維護的，可以在這裡查看。

Table of Contents

1. Single Responsibility
2. IIFE
3. Modules
4. Controllers
5. Services
6. Factories
7. Data Services
8. Directives
9. Resolving Promises for a Controller
10. Manual Annotating for Dependency Injection
11. Minification and Annotation
12. Exception Handling
13. Naming
14. Application Structure LIFT Principle
15. Application Structure
16. Modularity
17. Startup Logic
18. Angular $ Wrapper Services
19. Testing
20. Animations
21. Comments
22. JSHint
23. JSCS
24. Constants
25. File Templates and Snippets
26. Yeoman Generator
27. Routing
28. Task Automation
29. Filters
30. Angular Docs
31. Contributing
32. License

Single Responsibility

Rule of 1

[Style Y001]

• Define 1 component per file.

• 一個檔案裡面只定義一個Component

  The following example defines the app module and its dependencies, defines a controller, and defines a factory all in the same file.

  下面這個範例在同一個檔案裡面定義了app module以及他的依賴，另外又定義了一個controller以及一個factory。

  /* 不建議 */
  angular
    .module('app', ['ngRoute'])
    .controller('SomeController', SomeController)
    .factory('someFactory', someFactory);
  function SomeController() { }
  function someFactory() { }

  The same components are now separated into their own files.

  現在我們把每個Componet分別寫在不同的檔案裡

  /* 建議 */
  // app.module.js
  angular
    .module('app', ['ngRoute']);

  /* 建議 */
  // someController.js
  angular
    .module('app')
    .controller('SomeController', SomeController);
  function SomeController() { }

  /* 建議 */
  // someFactory.js
  angular
    .module('app')
    .factory('someFactory', someFactory);
  function someFactory() { }

回到頂部

IIFE

JavaScript Closures

[Style Y010]

• Wrap Angular components in an Immediately Invoked Function Expression (IIFE).

• 把Angular componets包裝到一個立即式(IIFE, Immediately Invoked Function Expression)裡面。

  Why?: An IIFE removes variables from the global scope. This helps prevent variables and function declarations from living longer than expected in the global scope, which also helps avoid variable collisions.

  為什麼？: IIFE會把來自全域的變數移除，這可以防止變數以及函式在全域中有比預期長的生命週期，也可以避免產生衝突。

  Why?: When your code is minified and bundled into a single file for deployment to a production server, you could have collisions of variables and many global variables. An IIFE protects you against both of these by providing variable scope for each file.

  為什麼？: 當你在壓縮或合併文件時，IIFE可以給每個文件一個單獨的function scope，避免變數產生衝突。

  /* avoid */
  // logger.js
  angular
    .module('app')
    .factory('logger', logger);
  // logger function is added as a global variable
  function logger() { }
  // storage.js
  angular
    .module('app')
    .factory('storage', storage);
  // storage function is added as a global variable
  function storage() { }

  /**
  * recommended
  *
  * no globals are left behind
  */
  // logger.js
  (function() {
    'use strict';
    angular
        .module('app')
        .factory('logger', logger);
    function logger() { }
  })();
  // storage.js
  (function() {
    'use strict';
    angular
        .module('app')
        .factory('storage', storage);
    function storage() { }
  })();

• Note: For brevity only, the rest of the examples in this guide may omit the IIFE syntax.

• 註：為了方便，下面的範例會省略IIFE

• Note: IIFE’s prevent test code from reaching private members like regular expressions or helper functions which are often good to unit test directly on their own. However you can test these through accessible members or by exposing them through their own component. For example placing helper functions, regular expressions or constants in their own factory or constant.

• 註：IIFE會防止test code存取私有的成員（例如正規表示式、helper函式等），這對於自身的單元測試有幫助。不過你也可以把這些私有的成員暴露出來進行測試，例如把它們放到factory或是constant裡面。

Back to top

Modules

Avoid Naming Collisions

避免命名衝突

[Style Y020]

• Use unique naming conventions with separators for sub-modules.

• 為sub-modules命名時使用帶有separators的命名規範。（譯註：指的就是parent.sub這樣的方式）

  Why?: Unique names help avoid module name collisions. Separators help define modules and their submodule hierarchy. For example app may be your root module while app.dashboard and app.users may be modules that are used as dependencies of app.

  為什麼？：避免module的名稱衝突，而且separators可以幫助定義模組的層次。例如app可能是你的root module，而app.dashboard跟app.users則是依賴於app的sub module。

Definitions (aka Setters)

定義(aka Setters)

[Style Y021]

• Declare modules without a variable using the setter syntax.

• 宣告module的時候不要使用含有setter語法的變數。（譯註：簡單來說就是不需要宣告一個變數給module）

  Why?: With 1 component per file, there is rarely a need to introduce a variable for the module.

  為什麼？：當每個檔案中只有一個component的時候，不太需要宣告一個變數給他。

  /* avoid */
  var app = angular.module('app', [
    'ngAnimate',
    'ngRoute',
    'app.shared',
    'app.dashboard'
  ]);

  Instead use the simple setter syntax.
  用簡單的setter語法來取代。

  /* recommended */
  angular
    .module('app', [
        'ngAnimate',
        'ngRoute',
        'app.shared',
        'app.dashboard'
    ]);

Getters

[Style Y022]

• When using a module, avoid using a variable and instead use chaining with the getter syntax.

• 當使用一個module的時候，儘量用鏈式語法（chaining），而不是使用變數。

  Why?: This produces more readable code and avoids variable collisions or leaks.

  為什麼？：這樣的寫法可讀性更高，而且可以避免衝突或者洩漏。

  /* avoid */
  var app = angular.module('app');
  app.controller('SomeController', SomeController);
  function SomeController() { }

  /* recommended */
  angular
    .module('app')
    .controller('SomeController', SomeController);
  function SomeController() { }

Setting vs Getting

[Style Y023]

• Only set once and get for all other instances.

• 應該只set一次，並且讓其他的實例取用

  Why?: A module should only be created once, then retrieved from that point and after.

  為什麼？：一個module應該只建立一次，在這之後的地方都應該取用他

  • Use angular.module('app', []); to set a module.
  • Use angular.module('app'); to get a module.

Named vs Anonymous Functions

[Style Y024]

• Use named functions instead of passing an anonymous function in as a callback.

• 在callback中用具名函式取代匿名函式

  Why?: This produces more readable code, is much easier to debug, and reduces the amount of nested callback code.

  為什麼？：這樣的寫法可讀性更高，更容易debug，而且可以避免太多層的callback code。

  /* avoid */
  angular
    .module('app')
    .controller('Dashboard', function() { })
    .factory('logger', function() { });

  /* recommended */
  // dashboard.js
  angular
    .module('app')
    .controller('Dashboard', Dashboard);
  function Dashboard() { }

  // logger.js
  angular
    .module('app')
    .factory('logger', logger);
  function logger() { }

Back to top

Controllers

controllerAs View Syntax

在View裡面使用controllerAs語法

[Style Y030]

• Use the controllerAs syntax over the classic controller with $scope syntax.

• 用controllerAs語法來取代一般的語法。

  Why?: Controllers are constructed, “newed” up, and provide a single new instance, and the controllerAs syntax is closer to that of a JavaScript constructor than the classic $scope syntax.

  為什麼？：Controller會被建構，new出來，並且提供一個新的實例；而且controllerAs在語法上比較接近javascript的建構式。

  Why?: It promotes the use of binding to a “dotted” object in the View (e.g. customer.name instead of name), which is more contextual, easier to read, and avoids any reference issues that may occur without “dotting”.

  為什麼？：促使你在View裡面使用有.的Object做binding（例如用customer.name取代name），這種寫法提高了可讀性、跟上下文的關聯性，並且避免在使用一般寫法時可能會發生的reference issue。

  Why?: Helps avoid using $parent calls in Views with nested controllers.

  為什麼？：避免你在多層嵌套的controller裡面使用$parent呼叫。

  <!-- avoid -->
  <div ng-controller="Customer">
    {{ name }}
  </div>

  <!-- recommended -->
  <div ng-controller="Customer as customer">
    {{ customer.name }}
  </div>

controllerAs Controller Syntax

在Controller裡面使用controllerAs語法

[Style Y031]

• Use the controllerAs syntax over the classic controller with $scope syntax.

• 用controllerAs語法來取代傳統的controller with $scope語法。

• The controllerAs syntax uses this inside controllers which gets bound to $scope

• controllerAs語法在controller中會用this來取代$scope

  Why?: controllerAs is syntactic sugar over $scope. You can still bind to the View and still access $scope methods.

  為什麼？：controllerAs語法只是用來取代$scope的語法糖，你仍然可以把資料綁定到view上，也可以使用$scope的方法。

  Why?: Helps avoid the temptation of using $scope methods inside a controller when it may otherwise be better to avoid them or move them to a factory. Consider using $scope in a factory, or if in a controller just when needed. For example when publishing and subscribing events using $emit, $broadcast, or $on consider moving these uses to a factory and invoke from the controller.

  為什麼？：這種語法可以幫助你抵擋在不正確時機使用$scope的方法的誘惑，例如你有更好的做法，或是他可以搬到factory裡面時。你應該只在必要時才在controller裡使用$scope，其他的時候應該在factory裡面使
  用。例如當你要使用$emit，$broadcast, 以及$on來收發事件時，應該把它們寫在factory裡，然後再從controller取用。

  /* avoid */
  function Customer($scope) {
    $scope.name = {};
    $scope.sendMessage = function() { };
  }

  /* recommended - but see next section */
  function Customer() {
    this.name = {};
    this.sendMessage = function() { };
  }

controllerAs with vm

[Style Y032]

• Use a capture variable for this when using the controllerAs syntax. Choose a consistent variable name such as vm, which stands for ViewModel.

• 當你在使用controllerAs語法的時候，給this一個capture variable，例如vm（ViewModel）。

  Why?: The this keyword is contextual and when used within a function inside a controller may change its context. Capturing the context of this avoids encountering this problem.

  Why?：因為this會受到function scope的影響而指向不同的context，所以在一開始就給他一個capture variable來避免這些問題。

  /* avoid */
  function Customer() {
    this.name = {};
    this.sendMessage = function() { };
  }

  /* recommended */
  function Customer() {
    var vm = this;
    vm.name = {};
    vm.sendMessage = function() { };
  }

  Note: You can avoid any jshint warnings by placing the comment below above the line of code. However it is not needed when the function is named using UpperCasing, as this convention means it is a constructor function, which is what a controller is in Angular.

  註：你可以用下面的方式來避免jshint拋出警告。不過這在函式用大寫開頭命名（通常是代表他是構造函式）的時候是不必要的。

  /* jshint validthis: true */
  var vm = this;

  Note: When creating watches in a controller using controller as, you can watch the vm.* member using the following syntax. (Create watches with caution as they add more load to the digest cycle.)

  註：當你用controllerAs語法在controller中建立watches時，可以參考下面的方式。（建立watches的時候要謹慎，因為他會對digest cycle帶來負擔）

  <input ng-model="vm.title"/>

  function SomeController($scope, $log) {
    var vm = this;
    vm.title = 'Some Title';
    $scope.$watch('vm.title', function(current, original) {
        $log.info('vm.title was %s', original);
        $log.info('vm.title is now %s', current);
    });
  }

Bindable Members Up Top

[Style Y033]

• Place bindable members at the top of the controller, alphabetized, and not spread through the controller code.

  Why?: Placing bindable members at the top makes it easy to read and helps you instantly identify which members of the controller can be bound and used in the View.

  Why?: Setting anonymous functions in-line can be easy, but when those functions are more than 1 line of code they can reduce the readability. Defining the functions below the bindable members (the functions will be hoisted) moves the implementation details down, keeps the bindable members up top, and makes it easier to read.

  /* avoid */
  function Sessions() {
    var vm = this;
    vm.gotoSession = function() {
      /* ... */
    };
    vm.refresh = function() {
      /* ... */
    };
    vm.search = function() {
      /* ... */
    };
    vm.sessions = [];
    vm.title = 'Sessions';

  /* recommended */
  function Sessions() {
    var vm = this;
    vm.gotoSession = gotoSession;
    vm.refresh = refresh;
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';
    ////////////
    function gotoSession() {
      /* */
    }
    function refresh() {
      /* */
    }
    function search() {
      /* */
    }

  

  Note: If the function is a 1 liner consider keeping it right up top, as long as readability is not affected.

  /* avoid */
  function Sessions(data) {
    var vm = this;
    vm.gotoSession = gotoSession;
    vm.refresh = function() {
        /**
         * lines
         * of
         * code
         * affects
         * readability
         */
    };
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';

  /* recommended */
  function Sessions(dataservice) {
    var vm = this;
    vm.gotoSession = gotoSession;
    vm.refresh = dataservice.refresh; // 1 liner is OK
    vm.search = search;
    vm.sessions = [];
    vm.title = 'Sessions';

Function Declarations to Hide Implementation Details

[Style Y034]

• Use function declarations to hide implementation details. Keep your bindable members up top. When you need to bind a function in a controller, point it to a function declaration that appears later in the file. This is tied directly to the section Bindable Members Up Top. For more details see this post.

  Why?: Placing bindable members at the top makes it easy to read and helps you instantly identify which members of the controller can be bound and used in the View. (Same as above.)

  Why?: Placing the implementation details of a function later in the file moves that complexity out of view so you can see the important stuff up top.

  Why?: Function declaration are hoisted so there are no concerns over using a function before it is defined (as there would be with function expressions).

  Why?: You never have to worry with function declarations that moving var a before var b will break your code because a depends on b.

  Why?: Order is critical with function expressions

  /**
  * avoid
  * Using function expressions.
  */
  function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';
    var activate = function() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }
    var getAvengers = function() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }
    vm.getAvengers = getAvengers;
    activate();
  }

  Notice that the important stuff is scattered in the preceding example. In the example below, notice that the important stuff is up top. For example, the members bound to the controller such as vm.avengers and vm.title. The implementation details are down below. This is just easier to read.

  /*
  * recommend
  * Using function declarations
  * and bindable members up top.
  */
  function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];
    vm.getAvengers = getAvengers;
    vm.title = 'Avengers';
    activate();
    function activate() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }
    function getAvengers() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }
  }

Defer Controller Logic to Services

[Style Y035]

• Defer logic in a controller by delegating to services and factories.

  Why?: Logic may be reused by multiple controllers when placed within a service and exposed via a function.

  Why?: Logic in a service can more easily be isolated in a unit test, while the calling logic in the controller can be easily mocked.

  Why?: Removes dependencies and hides implementation details from the controller.

  Why?: Keeps the controller slim, trim, and focused.

  /* avoid */
  function Order($http, $q, config, userInfo) {
    var vm = this;
    vm.checkCredit = checkCredit;
    vm.isCreditOk;
    vm.total = 0;
    function checkCredit() {
        var settings = {};
        // Get the credit service base URL from config
        // Set credit service required headers
        // Prepare URL query string or data object with request data
        // Add user-identifying info so service gets the right credit limit for this user.
        // Use JSONP for this browser if it doesn't support CORS
        return $http.get(settings)
            .then(function(data) {
             // Unpack JSON data in the response object
               // to find maxRemainingAmount
               vm.isCreditOk = vm.total <= maxRemainingAmount
            })
            .catch(function(error) {
               // Interpret error
               // Cope w/ timeout? retry? try alternate service?
               // Re-reject with appropriate error for a user to see
            });
    };
  }

  /* recommended */
  function Order(creditService) {
    var vm = this;
    vm.checkCredit = checkCredit;
    vm.isCreditOk;
    vm.total = 0;
    function checkCredit() {
       return creditService.isOrderTotalOk(vm.total)
    .then(function(isOk) { vm.isCreditOk = isOk; })
          .catch(showServiceError);
    };
  }

Keep Controllers Focused

[Style Y037]

• Define a controller for a view, and try not to reuse the controller for other views. Instead, move reusable logic to factories and keep the controller simple and focused on its view.

  Why?: Reusing controllers with several views is brittle and good end to end (e2e) test coverage is required to ensure stability across large applications.

Assigning Controllers

[Style Y038]

• When a controller must be paired with a view and either component may be re-used by other controllers or views, define controllers along with their routes.

  Note: If a View is loaded via another means besides a route, then use the ng-controller="Avengers as vm" syntax.

  Why?: Pairing the controller in the route allows different routes to invoke different pairs of controllers and views. When controllers are assigned in the view using ng-controller, that view is always associated with the same controller.

  /* avoid - when using with a route and dynamic pairing is desired */
  // route-config.js
  angular
    .module('app')
    .config(config);
  function config($routeProvider) {
    $routeProvider
        .when('/avengers', {
          templateUrl: 'avengers.html'
        });
  }

  <!-- avengers.html -->
  <div ng-controller="Avengers as vm">
  </div>

  /* recommended */
  // route-config.js
  angular
    .module('app')
    .config(config);
  function config($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm'
        });
  }

  <!-- avengers.html -->
  <div>
  </div>

Back to top

Services

Singletons

[Style Y040]

• Services are instantiated with the new keyword, use this for public methods and variables. Since these are so similar to factories, use a factory instead for consistency.

  Note: All Angular services are singletons. This means that there is only one instance of a given service per injector.

  // service
  angular
    .module('app')
    .service('logger', logger);
  function logger() {
  this.logError = function(msg) {
    /* */
  };
  }

  // factory
  angular
    .module('app')
    .factory('logger', logger);
  function logger() {
    return {
        logError: function(msg) {
          /* */
        }
   };
  }

Back to top

Factories

Single Responsibility

[Style Y050]

• Factories should have a single responsibility, that is encapsulated by its context. Once a factory begins to exceed that singular purpose, a new factory should be created.

Singletons

[Style Y051]

• Factories are singletons and return an object that contains the members of the service.

  Note: All Angular services are singletons.

Accessible Members Up Top

[Style Y052]

• Expose the callable members of the service (its interface) at the top, using a technique derived from the Revealing Module Pattern.

  Why?: Placing the callable members at the top makes it easy to read and helps you instantly identify which members of the service can be called and must be unit tested (and/or mocked).

  Why?: This is especially helpful when the file gets longer as it helps avoid the need to scroll to see what is exposed.

  Why?: Setting functions as you go can be easy, but when those functions are more than 1 line of code they can reduce the readability and cause more scrolling. Defining the callable interface via the returned service moves the implementation details down, keeps the callable interface up top, and makes it easier to read.

  /* avoid */
  function dataService() {
  var someValue = '';
  function save() {
    /* */
  };
  function validate() {
    /* */
  };
  return {
      save: save,
      someValue: someValue,
      validate: validate
  };
  }

  /* recommended */
  function dataService() {
    var someValue = '';
    var service = {
        save: save,
        someValue: someValue,
        validate: validate
    };
    return service;
    ////////////
    function save() {
        /* */
    };
    function validate() {
        /* */
    };
  }

  This way bindings are mirrored across the host object, primitive values cannot update alone using the revealing module pattern

  

Function Declarations to Hide Implementation Details

[Style Y053]

• Use function declarations to hide implementation details. Keep your accessible members of the factory up top. Point those to function declarations that appears later in the file. For more details see this post.

  Why?: Placing accessible members at the top makes it easy to read and helps you instantly identify which functions of the factory you can access externally.

  Why?: Placing the implementation details of a function later in the file moves that complexity out of view so you can see the important stuff up top.

  Why?: Function declaration are hoisted so there are no concerns over using a function before it is defined (as there would be with function expressions).

  Why?: You never have to worry with function declarations that moving var a before var b will break your code because a depends on b.

  Why?: Order is critical with function expressions

  /**
  * avoid
  * Using function expressions
  */
  function dataservice($http, $location, $q, exception, logger) {
    var isPrimed = false;
    var primePromise;
    var getAvengers = function() {
        // implementation details go here
    };
    var getAvengerCount = function() {
        // implementation details go here
    };
    var getAvengersCast = function() {
       // implementation details go here
    };
    var prime = function() {
       // implementation details go here
    };
    var ready = function(nextPromises) {
        // implementation details go here
    };
    var service = {
        getAvengersCast: getAvengersCast,
        getAvengerCount: getAvengerCount,
        getAvengers: getAvengers,
        ready: ready
    };
    return service;
  }

  /**
  * recommended
  * Using function declarations
  * and accessible members up top.
  */
  function dataservice($http, $location, $q, exception, logger) {
    var isPrimed = false;
    var primePromise;
    var service = {
        getAvengersCast: getAvengersCast,
        getAvengerCount: getAvengerCount,
        getAvengers: getAvengers,
        ready: ready
    };
    return service;
    ////////////
    function getAvengers() {
        // implementation details go here
    }
    function getAvengerCount() {
        // implementation details go here
    }
    function getAvengersCast() {
        // implementation details go here
    }
    function prime() {
        // implementation details go here
    }
    function ready(nextPromises) {
        // implementation details go here
    }
  }

Back to top

Data Services

Separate Data Calls

[Style Y060]

• Refactor logic for making data operations and interacting with data to a factory. Make data services responsible for XHR calls, local storage, stashing in memory, or any other data operations.

  Why?: The controller’s responsibility is for the presentation and gathering of information for the view. It should not care how it gets the data, just that it knows who to ask for it. Separating the data services moves the logic on how to get it to the data service, and lets the controller be simpler and more focused on the view.

  Why?: This makes it easier to test (mock or real) the data calls when testing a controller that uses a data service.

  Why?: Data service implementation may have very specific code to handle the data repository. This may include headers, how to talk to the data, or other services such as $http. Separating the logic into a data service encapsulates this logic in a single place hiding the implementation from the outside consumers (perhaps a controller), also making it easier to change the implementation.

  /* recommended */
  // dataservice factory
  angular
    .module('app.core')
    .factory('dataservice', dataservice);
  dataservice.$inject = ['$http', 'logger'];
  function dataservice($http, logger) {
    return {
        getAvengers: getAvengers
    };
    function getAvengers() {
        return $http.get('/api/maa')
            .then(getAvengersComplete)
            .catch(getAvengersFailed);
        function getAvengersComplete(response) {
            return response.data.results;
        }
        function getAvengersFailed(error) {
            logger.error('XHR Failed for getAvengers.' + error.data);
        }
    }
  }

  Note: The data service is called from consumers, such as a controller, hiding the implementation from the consumers, as shown below.

  /* recommended */
  // controller calling the dataservice factory
  angular
    .module('app.avengers')
    .controller('Avengers', Avengers);
  Avengers.$inject = ['dataservice', 'logger'];
  function Avengers(dataservice, logger) {
    var vm = this;
    vm.avengers = [];
    activate();
    function activate() {
        return getAvengers().then(function() {
            logger.info('Activated Avengers View');
        });
    }
    function getAvengers() {
        return dataservice.getAvengers()
            .then(function(data) {
                vm.avengers = data;
                return vm.avengers;
            });
    }
  }

Return a Promise from Data Calls

[Style Y061]

• When calling a data service that returns a promise such as $http, return a promise in your calling function too.

  Why?: You can chain the promises together and take further action after the data call completes and resolves or rejects the promise.

  /* recommended */
  activate();
  function activate() {
    /**
     * Step 1
     * Ask the getAvengers function for the
     * avenger data and wait for the promise
     */
    return getAvengers().then(function() {
        /**
         * Step 4
         * Perform an action on resolve of final promise
         */
        logger.info('Activated Avengers View');
    });
  }
  function getAvengers() {
      /**
       * Step 2
       * Ask the data service for the data and wait
       * for the promise
       */
      return dataservice.getAvengers()
          .then(function(data) {
              /**
               * Step 3
               * set the data and resolve the promise
               */
              vm.avengers = data;
              return vm.avengers;
      });
  }

  Back to top

Directives

Limit 1 Per File

[Style Y070]

• Create one directive per file. Name the file for the directive.

  Why?: It is easy to mash all the directives in one file, but difficult to then break those out so some are shared across apps, some across modules, some just for one module.

  Why?: One directive per file is easy to maintain.

  Note: “Best Practice: Directives should clean up after themselves. You can use element.on('$destroy', ...) or scope.$on('$destroy', ...) to run a clean-up function when the directive is removed” … from the Angular documentation

  /* avoid */
  /* directives.js */
  angular
    .module('app.widgets')
    /* order directive that is specific to the order module */
    .directive('orderCalendarRange', orderCalendarRange)
    /* sales directive that can be used anywhere across the sales app */
    .directive('salesCustomerInfo', salesCustomerInfo)
    /* spinner directive that can be used anywhere across apps */
    .directive('sharedSpinner', sharedSpinner);
  function orderCalendarRange() {
    /* implementation details */
  }
  function salesCustomerInfo() {
    /* implementation details */
  }
  function sharedSpinner() {
    /* implementation details */
  }

  /* recommended */
  /* calendarRange.directive.js */
  /**
  * @desc order directive that is specific to the order module at a company named Acme
  * @example <div acme-order-calendar-range></div>
  */
  angular
    .module('sales.order')
    .directive('acmeOrderCalendarRange', orderCalendarRange);
  function orderCalendarRange() {
    /* implementation details */
  }

  /* recommended */
  /* customerInfo.directive.js */
  /**
  * @desc sales directive that can be used anywhere across the sales app at a company named Acme
  * @example <div acme-sales-customer-info></div>
  */
  angular
    .module('sales.widgets')
    .directive('acmeSalesCustomerInfo', salesCustomerInfo);
  function salesCustomerInfo() {
    /* implementation details */
  }

  /* recommended */
  /* spinner.directive.js */
  /**
  * @desc spinner directive that can be used anywhere across apps at a company named Acme
  * @example <div acme-shared-spinner></div>
  */
  angular
    .module('shared.widgets')
    .directive('acmeSharedSpinner', sharedSpinner);
  function sharedSpinner() {
    /* implementation details */
  }

  Note: There are many naming options for directives, especially since they can be used in narrow or wide scopes. Choose one that makes the directive and its file name distinct and clear. Some examples are below, but see the Naming section for more recommendations.

Manipulate DOM in a Directive

[Style Y072]

• When manipulating the DOM directly, use a directive. If alternative ways can be used such as using CSS to set styles or the animation services, Angular templating, ngShow or ngHide, then use those instead. For example, if the directive simply hides and shows, use ngHide/ngShow.

  Why?: DOM manipulation can be difficult to test, debug, and there are often better ways (e.g. CSS, animations, templates)

Provide a Unique Directive Prefix

[Style Y073]

• Provide a short, unique and descriptive directive prefix such as acmeSalesCustomerInfo which would be declared in HTML as acme-sales-customer-info.

  Why?: The unique short prefix identifies the directive’s context and origin. For example a prefix of cc- may indicate that the directive is part of a CodeCamper app while acme- may indicate a directive for the Acme company.

  Note: Avoid ng- as these are reserved for Angular directives. Research widely used directives to avoid naming conflicts, such as ion- for the Ionic Framework.

Restrict to Elements and Attributes

[Style Y074]

• When creating a directive that makes sense as a stand-alone element, allow restrict E (custom element) and optionally restrict A (custom attribute). Generally, if it could be its own control, E is appropriate. General guideline is allow EA but lean towards implementing as an element when it’s stand-alone and as an attribute when it enhances its existing DOM element.

  Why?: It makes sense.

  Why?: While we can allow the directive to be used as a class, if the directive is truly acting as an element it makes more sense as an element or at least as an attribute.

  Note: EA is the default for Angular 1.3 +

  <!-- avoid -->
  <div class="my-calendar-range"></div>

  /* avoid */
  angular
    .module('app.widgets')
    .directive('myCalendarRange', myCalendarRange);
  function myCalendarRange() {
    var directive = {
        link: link,
        templateUrl: '/template/is/located/here.html',
        restrict: 'C'
    };
    return directive;
    function link(scope, element, attrs) {
      /* */
    }
  }

  <!-- recommended -->
  <my-calendar-range></my-calendar-range>
  <div my-calendar-range></div>

  /* recommended */
  angular
    .module('app.widgets')
    .directive('myCalendarRange', myCalendarRange);
  function myCalendarRange() {
    var directive = {
        link: link,
        templateUrl: '/template/is/located/here.html',
        restrict: 'EA'
    };
    return directive;
    function link(scope, element, attrs) {
      /* */
    }
  }

Directives and ControllerAs

[Style Y075]

• Use controller as syntax with a directive to be consistent with using controller as with view and controller pairings.

  Why?: It makes sense and it’s not difficult.

  Note: The directive below demonstrates some of the ways you can use scope inside of link and directive controllers, using controllerAs. I in-lined the template just to keep it all in one place.

  Note: Regarding dependency injection, see Manually Identify Dependencies.

  Note: Note that the directive’s controller is outside the directive’s closure. This style eliminates issues where the injection gets created as unreachable code after a return.

  <div my-example max="77"></div>

  angular
    .module('app')
    .directive('myExample', myExample);
  function myExample() {
    var directive = {
        restrict: 'EA',
        templateUrl: 'app/feature/example.directive.html',
        scope: {
            max: '='
        },
        link: linkFunc,
        controller: ExampleController,
          controllerAs: 'vm',
          bindToController: true // because the scope is isolated
      };
    return directive;
    function linkFunc(scope, el, attr, ctrl) {
        console.log('LINK: scope.min = %s *** should be undefined', scope.min);
        console.log('LINK: scope.max = %s *** should be undefined', scope.max);
        console.log('LINK: scope.vm.min = %s', scope.vm.min);
        console.log('LINK: scope.vm.max = %s', scope.vm.max);
    }
  }
  ExampleController.$inject = ['$scope'];
  function ExampleController($scope) {
    // Injecting $scope just for comparison
    var vm = this;
    vm.min = 3;
    console.log('CTRL: $scope.vm.min = %s', $scope.vm.min);
    console.log('CTRL: $scope.vm.max = %s', $scope.vm.max);
    console.log('CTRL: vm.min = %s', vm.min);
    console.log('CTRL: vm.max = %s', vm.max);
  }

  <!-- example.directive.html -->
  <div>hello world</div>
  <div>max={{vm.max}}<input ng-model="vm.max"/></div>
  <div>min={{vm.min}}<input ng-model="vm.min"/></div>

[Style Y076]

• Use bindToController = true when using controller as syntax with a directive when you want to bind the outer scope to the directive’s controller’s scope.

  Why?: It makes it easy to bind outer scope to the directive’s controller scope.

  Note: bindToController was introduced in Angular 1.3.0.

  <div my-example max="77"></div>

  angular
    .module('app')
    .directive('myExample', myExample);
  function myExample() {
    var directive = {
        restrict: 'EA',
        templateUrl: 'app/feature/example.directive.html',
        scope: {
            max: '='
        },
        controller: ExampleController,
        controllerAs: 'vm',
        bindToController: true
    };
    return directive;
  }
  function ExampleController() {
    var vm = this;
    vm.min = 3;
    console.log('CTRL: vm.min = %s', vm.min);
    console.log('CTRL: vm.max = %s', vm.max);
  }

  <!-- example.directive.html -->
  <div>hello world</div>
  <div>max={{vm.max}}<input ng-model="vm.max"/></div>
  <div>min={{vm.min}}<input ng-model="vm.min"/></div>

Back to top

Resolving Promises for a Controller

Controller Activation Promises

[Style Y080]

• Resolve start-up logic for a controller in an activate function.

  Why?: Placing start-up logic in a consistent place in the controller makes it easier to locate, more consistent to test, and helps avoid spreading out the activation logic across the controller.

  Why?: The controller activate makes it convenient to re-use the logic for a refresh for the controller/View, keeps the logic together, gets the user to the View faster, makes animations easy on the ng-view or ui-view, and feels snappier to the user.

  Note: If you need to conditionally cancel the route before you start use the controller, use a route resolve instead.

  /* avoid */
  function Avengers(dataservice) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';
    dataservice.getAvengers().then(function(data) {
        vm.avengers = data;
        return vm.avengers;
    });
  }

  /* recommended */
  function Avengers(dataservice) {
    var vm = this;
    vm.avengers = [];
    vm.title = 'Avengers';
    activate();
    ////////////
    function activate() {
        return dataservice.getAvengers().then(function(data) {
            vm.avengers = data;
            return vm.avengers;
        });
    }
  }

Route Resolve Promises

[Style Y081]

• When a controller depends on a promise to be resolved before the controller is activated, resolve those dependencies in the $routeProvider before the controller logic is executed. If you need to conditionally cancel a route before the controller is activated, use a route resolver.

• Use a route resolve when you want to decide to cancel the route before ever transitioning to the View.

  Why?: A controller may require data before it loads. That data may come from a promise via a custom factory or $http. Using a route resolve allows the promise to resolve before the controller logic executes, so it might take action based on that data from the promise.

  Why?: The code executes after the route and in the controller’s activate function. The View starts to load right away. Data binding kicks in when the activate promise resolves. A “busy” animation can be shown during the view transition (via ng-view or ui-view)

  Note: The code executes before the route via a promise. Rejecting the promise cancels the route. Resolve makes the new view wait for the route to resolve. A “busy” animation can be shown before the resolve and through the view transition. If you want to get to the View faster and do not require a checkpoint to decide if you can get to the View, consider the controller activate technique instead.

  /* avoid */
  angular
    .module('app')
    .controller('Avengers', Avengers);
  function Avengers(movieService) {
    var vm = this;
    // unresolved
    vm.movies;
    // resolved asynchronously
    movieService.getMovies().then(function(response) {
        vm.movies = response.movies;
    });
  }

  /* better */
  // route-config.js
  angular
    .module('app')
    .config(config);
  function config($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm',
            resolve: {
                moviesPrepService: function(movieService) {
                    return movieService.getMovies();
                }
            }
        });
  }
  // avengers.js
  angular
    .module('app')
    .controller('Avengers', Avengers);
  Avengers.$inject = ['moviesPrepService'];
  function Avengers(moviesPrepService) {
      var vm = this;
      vm.movies = moviesPrepService.movies;
  }

  Note: The example below shows the route resolve points to a named function, which is easier to debug and easier to handle dependency injection.

  /* even better */
  // route-config.js
  angular
    .module('app')
    .config(config);
  function config($routeProvider) {
    $routeProvider
        .when('/avengers', {
            templateUrl: 'avengers.html',
            controller: 'Avengers',
            controllerAs: 'vm',
            resolve: {
                moviesPrepService: moviesPrepService
            }
        });
  }
  function moviePrepService(movieService) {
    return movieService.getMovies();
  }
  // avengers.js
  angular
    .module('app')
    .controller('Avengers', Avengers);
  Avengers.$inject = ['moviesPrepService'];
  function Avengers(moviesPrepService) {
      var vm = this;
      vm.movies = moviesPrepService.movies;
  }

  Note: The code example’s dependency on movieService is not minification safe on its own. For details on how to make this code minification safe, see the sections on dependency injection and on minification and annotation.

Back to top

Manual Annotating for Dependency Injection

UnSafe from Minification

[Style Y090]

• Avoid using the shortcut syntax of declaring dependencies without using a minification-safe approach.

  Why?: The parameters to the component (e.g. controller, factory, etc) will be converted to mangled variables. For example, common and dataservice may become a or b and not be found by Angular.

  /* avoid - not minification-safe*/
  angular
      .module('app')
      .controller('Dashboard', Dashboard);
  function Dashboard(common, dataservice) {
  }

  This code may produce mangled variables when minified and thus cause runtime errors.

  /* avoid - not minification-safe*/
  angular.module('app').controller('Dashboard', d);function d(a, b) { }

Manually Identify Dependencies

[Style Y091]

• Use $inject to manually identify your dependencies for Angular components.

  Why?: This technique mirrors the technique used by ng-annotate, which I recommend for automating the creation of minification safe dependencies. If ng-annotate detects injection has already been made, it will not duplicate it.

  Why?: This safeguards your dependencies from being vulnerable to minification issues when parameters may be mangled. For example, common and dataservice may become a or b and not be found by Angular.

  Why?: Avoid creating in-line dependencies as long lists can be difficult to read in the array. Also it can be confusing that the array is a series of strings while the last item is the component’s function.

  /* avoid */
  angular
      .module('app')
      .controller('Dashboard',
          ['$location', '$routeParams', 'common', 'dataservice',
              function Dashboard($location, $routeParams, common, dataservice) {}
          ]);

  /* avoid */
  angular
    .module('app')
    .controller('Dashboard',
        ['$location', '$routeParams', 'common', 'dataservice', Dashboard]);
  function Dashboard($location, $routeParams, common, dataservice) {
  }

  /* recommended */
  angular
      .module('app')
      .controller('Dashboard', Dashboard);
  Dashboard.$inject = ['$location', '$routeParams', 'common', 'dataservice'];
  function Dashboard($location, $routeParams, common, dataservice) {
  }

  Note: When your function is below a return statement the $inject may be unreachable (this may happen in a directive). You can solve this by moving the Controller outside of the directive.

  /* avoid */
  // inside a directive definition
  function outer() {
      var ddo = {
          controller: DashboardPanelController,
          controllerAs: 'vm'
      };
      return ddo;
      DashboardPanelController.$inject = ['logger']; // Unreachable
      function DashboardPanelController(logger) {
      }
  }

  /* recommended */
  // outside a directive definition
  function outer() {
      var ddo = {
          controller: DashboardPanelController,
          controllerAs: 'vm'
      };
      return ddo;
  }
  DashboardPanelController.$inject = ['logger'];
  function DashboardPanelController(logger) {
  }

Manually Identify Route Resolver Dependencies

[Style Y092]

• Use $inject to manually identify your route resolver dependencies for Angular components.

  Why?: This technique breaks out the anonymous function for the route resolver, making it easier to read.

  Why?: An $inject statement can easily precede the resolver to handle making any dependencies minification safe.

  /* recommended */
  function config($routeProvider) {
      $routeProvider
          .when('/avengers', {
              templateUrl: 'avengers.html',
              controller: 'AvengersController',
              controllerAs: 'vm',
              resolve: {
                  moviesPrepService: moviePrepService
              }
          });
  }
  moviePrepService.$inject = ['movieService'];
  function moviePrepService(movieService) {
      return movieService.getMovies();
  }

Back to top

Minification and Annotation

ng-annotate

[Style Y100]

• Use ng-annotate for Gulp or Grunt and comment functions that need automated dependency injection using /** @ngInject */

  Why?: This safeguards your code from any dependencies that may not be using minification-safe practices.

  Why?: ng-min is deprecated

  I prefer Gulp as I feel it is easier to write, to read, and to debug.

  The following code is not using minification safe dependencies.

  angular
      .module('app')
      .controller('Avengers', Avengers);
  /* @ngInject */
  function Avengers(storageService, avengerService) {
      var vm = this;
      vm.heroSearch = '';
      vm.storeHero = storeHero;
      function storeHero() {
          var hero = avengerService.find(vm.heroSearch);
          storageService.save(hero.name, hero);
      }
  }

  When the above code is run through ng-annotate it will produce the following output with the $inject annotation and become minification-safe.

  angular
      .module('app')
      .controller('Avengers', Avengers);
  /* @ngInject */
  function Avengers(storageService, avengerService) {
      var vm = this;
      vm.heroSearch = '';
      vm.storeHero = storeHero;
      function storeHero() {
          var hero = avengerService.find(vm.heroSearch);
          storageService.save(hero.name, hero);
      }
  }
  Avengers.$inject = ['storageService', 'avengerService'];

  Note: If ng-annotate detects injection has already been made (e.g. @ngInject was detected), it will not duplicate the $inject code.

  Note: When using a route resolver you can prefix the resolver’s function with /* @ngInject */ and it will produce properly annotated code, keeping any injected dependencies minification safe.

  // Using @ngInject annotations
  function config($routeProvider) {
      $routeProvider
          .when('/avengers', {
              templateUrl: 'avengers.html',
              controller: 'Avengers',
              controllerAs: 'vm',
              resolve: { /* @ngInject */
                  moviesPrepService: function(movieService) {
                      return movieService.getMovies();
                  }
              }
          });
  }

  Note: Starting from Angular 1.3 you can use the ngApp directive’s ngStrictDi parameter to detect any potentially missing magnification safe dependencies. When present the injector will be created in “strict-di” mode causing the application to fail to invoke functions which do not use explicit function annotation (these may not be minification safe). Debugging info will be logged to the console to help track down the offending code. I prefer to only use ng-strict-di for debugging purposes only.
  <body ng-app="APP" ng-strict-di>

Use Gulp or Grunt for ng-annotate

[Style Y101]

• Use gulp-ng-annotate or grunt-ng-annotate in an automated build task. Inject /* @ngInject */ prior to any function that has dependencies.

  Why?: ng-annotate will catch most dependencies, but it sometimes requires hints using the /* @ngInject */ syntax.

  The following code is an example of a gulp task using ngAnnotate

  gulp.task('js', ['jshint'], function() {
      var source = pkg.paths.js;
      return gulp.src(source)
          .pipe(sourcemaps.init())
          .pipe(concat('all.min.js', {newLine: ';'}))
          // Annotate before uglify so the code get's min'd properly.
          .pipe(ngAnnotate({
              // true helps add where @ngInject is not used. It infers.
              // Doesn't work with resolve, so we must be explicit there
              add: true
          }))
          .pipe(bytediff.start())
          .pipe(uglify({mangle: true}))
          .pipe(bytediff.stop())
          .pipe(sourcemaps.write('./'))
          .pipe(gulp.dest(pkg.paths.dev));
  });

Back to top

Exception Handling

decorators

[Style Y110]

• Use a decorator, at config time using the $provide service, on the $exceptionHandler service to perform custom actions when exceptions occur.

  Why?: Provides a consistent way to handle uncaught Angular exceptions for development-time or run-time.

  Note: Another option is to override the service instead of using a decorator. This is a fine option, but if you want to keep the default behavior and extend it a decorator is recommended.

  /* recommended */
  angular
      .module('blocks.exception')
      .config(exceptionConfig);
  exceptionConfig.$inject = ['$provide'];
  function exceptionConfig($provide) {
      $provide.decorator('$exceptionHandler', extendExceptionHandler);
  }
  extendExceptionHandler.$inject = ['$delegate', 'toastr'];
  function extendExceptionHandler($delegate, toastr) {
      return function(exception, cause) {
          $delegate(exception, cause);
          var errorData = {
              exception: exception,
              cause: cause
          };
          /**
           * Could add the error to a service's collection,
           * add errors to $rootScope, log errors to remote web server,
           * or log locally. Or throw hard. It is entirely up to you.
           * throw exception;
           */
          toastr.error(exception.msg, errorData);
      };
  }

Exception Catchers

[Style Y111]

• Create a factory that exposes an interface to catch and gracefully handle exceptions.

  Why?: Provides a consistent way to catch exceptions that may be thrown in your code (e.g. during XHR calls or promise failures).

  Note: The exception catcher is good for catching and reacting to specific exceptions from calls that you know may throw one. For example, when making an XHR call to retrieve data from a remote web service and you want to catch any exceptions from that service and react uniquely.

  /* recommended */
  angular
      .module('blocks.exception')
      .factory('exception', exception);
  exception.$inject = ['logger'];
  function exception(logger) {
      var service = {
          catcher: catcher
      };
      return service;
      function catcher(message) {
          return function(reason) {
              logger.error(message, reason);
          };
      }
  }

Route Errors

[Style Y112]

• Handle and log all routing errors using $routeChangeError.

  Why?: Provides a consistent way to handle all routing errors.

  Why?: Potentially provides a better user experience if a routing error occurs and you route them to a friendly screen with more details or recovery options.

  /* recommended */
  var handlingRouteChangeError = false;
  function handleRoutingErrors() {
      /**
       * Route cancellation:
       * On routing error, go to the dashboard.
       * Provide an exit clause if it tries to do it twice.
       */
      $rootScope.$on('$routeChangeError',
          function(event, current, previous, rejection) {
              if (handlingRouteChangeError) { return; }
              handlingRouteChangeError = true;
              var destination = (current && (current.title ||
                  current.name || current.loadedTemplateUrl)) ||
                  'unknown target';
              var msg = 'Error routing to ' + destination + '. ' +
                  (rejection.msg || '');
              /**
               * Optionally log using a custom service or $log.
               * (Don't forget to inject custom service)
               */
              logger.warning(msg, [current]);
              /**
               * On routing error, go to another route/state.
               */
              $location.path('/');
          }
      );
  }

Back to top

Naming

Naming Guidelines

[Style Y120]

• Use consistent names for all components following a pattern that describes the component’s feature then (optionally) its type. My recommended pattern is feature.type.js. There are 2 names for most assets:

  • the file name (avengers.controller.js)
  • the registered component name with Angular (AvengersController)

  Why?: Naming conventions help provide a consistent way to find content at a glance. Consistency within the project is vital. Consistency with a team is important. Consistency across a company provides tremendous efficiency.

  Why?: The naming conventions should simply help you find your code faster and make it easier to understand.

Feature File Names

[Style Y121]

• Use consistent names for all components following a pattern that describes the component’s feature then (optionally) its type. My recommended pattern is feature.type.js.

  Why?: Provides a consistent way to quickly identify components.

  Why?: Provides pattern matching for any automated tasks.

  /**
   * common options
   */
  // Controllers
  avengers.js
  avengers.controller.js
  avengersController.js
  // Services/Factories
  logger.js
  logger.service.js
  loggerService.js

  /**
   * recommended
   */
  // controllers
  avengers.controller.js
  avengers.controller.spec.js
  // services/factories
  logger.service.js
  logger.service.spec.js
  // constants
  constants.js
  // module definition
  avengers.module.js
  // routes
  avengers.routes.js
  avengers.routes.spec.js
  // configuration
  avengers.config.js
  // directives
  avenger-profile.directive.js
  avenger-profile.directive.spec.js

  Note: Another common convention is naming controller files without the word controller in the file name such as avengers.js instead of avengers.controller.js. All other conventions still hold using a suffix of the type. Controllers are the most common type of component so this just saves typing and is still easily identifiable. I recommend you choose 1 convention and be consistent for your team. My preference is avengers.controller.js.

  /**
   * recommended
   */
  // Controllers
  avengers.js
  avengers.spec.js

Test File Names

[Style Y122]

• Name test specifications similar to the component they test with a suffix of spec.

  Why?: Provides a consistent way to quickly identify components.

  Why?: Provides pattern matching for karma or other test runners.

  /**
   * recommended
   */
  avengers.controller.spec.js
  logger.service.spec.js
  avengers.routes.spec.js
  avenger-profile.directive.spec.js

Controller Names

[Style Y123]

• Use consistent names for all controllers named after their feature. Use UpperCamelCase for controllers, as they are constructors.

  Why?: Provides a consistent way to quickly identify and reference controllers.

  Why?: UpperCamelCase is conventional for identifying object that can be instantiated using a constructor.

  /**
   * recommended
   */
  // avengers.controller.js
  angular
      .module
      .controller('HeroAvengersController', HeroAvengersController);
  function HeroAvengersController() { }