Introduction:
This a quick guide for myself to check/review what pattern/style/standard should be followed during AngularJS application development. Please check the resources section for the links where the gurus have explained elaborately the reason behind each item in this post. Once someone gets the head around the explanations or becomes more advanced developer, this post will serve as a quick cheat sheet for a refresher and reference. Added a facts section which would help going through the practices to understand better.
Some quick facts:
Best practices items:
Resources:
1. https://github.com/johnpapa/angular-styleguide
2. https://github.com/toddmotto/angularjs-styleguide
3. http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript
4. http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code/
This a quick guide for myself to check/review what pattern/style/standard should be followed during AngularJS application development. Please check the resources section for the links where the gurus have explained elaborately the reason behind each item in this post. Once someone gets the head around the explanations or becomes more advanced developer, this post will serve as a quick cheat sheet for a refresher and reference. Added a facts section which would help going through the practices to understand better.
Some quick facts:
- All services (value, factory, service) in AngularJS are Singleton
- Service services are instantiated with the new keyword, need to use this for public methods and variables
- Factory services expose it's members (variable, function) using return{} defined in it
| Component | Practices to follow |
|---|---|
| Module | 1 - 11 |
| Controller | Module + (12, 13, 15, 16, 17, 18) |
| Service | Module + (14, 19) |
| Directive | Module + (20, 21, 22, 23, 24, 25) |
| Router | Module + (18) |
Best practices items:
- Create separate file for each controller/service/router/directiveReason: code separation, better testability of code, developers work on independently without being affected by others
- File name should follow -
. .js - Test file should use spec suffix.
. .spec.js - Application Structure should follow LIFT(Locate, Identify, Flat, Try to be DRY) Principle.
- Locating our code is easy
- Identify code at a glance
- Flat structure as long as we can
- Try to stay DRY (Don’t Repeat Yourself) or T-DRY
- Use unique naming conventions for modules and with separators for sub-modules
Reason: help avoid module name collisions - Put any member variables in any module on top
Reason: helps identify instantly what members are defined and used in the implementation flow - Use named functions instead of passing an anonymous function in as a callback. May ideal to use on major functions
Reason: easy to debug, reduces the amount of nested callback code, increases code readability - Declare any function in any module at the bottom. JavaScript anyway hoists the function definition at the top during execution
Reason: helps separate the implementation detail from the flow and increases readability - Use functional declaration over functional expression (declare and assign to a var)
Reason: removes the concern over using a function before it is defined. Code organization (moving a block of code up or down) won't break anything - Use IIFE scoping. Ideal solution should be creating build task to wrap the concatenated files inside an IIFE. IIFE - Immediately Invoked Function Expression.
Reason:to avoid polluting the global scope with custom function declarations - Consider manual annotation for dependency injection
Reason: to make the code safe of minification - Use the 'controller as' syntax over the classic $scope. Need to follow below steps for that -
- Use 'controller as' in view (HTML). Like - 'MyController as ctl'
- Refer any members using the controller reference. Like - 'ctl.aValue'
- In controller, use a capture variable and associate members to the capture variable. Like - 'var vm = this; vm.aValue = 'A Value';'
Reason: avoids any reference issues, gives way to write code on contextual manner, easier to read - Put bindable variables on top
Reason: helps identify instantly which members of the controller can be bound and used in the View - Put member variables on top
Reason: helps identify instantly which members can be called and must be unit tested - Defer logic in a controller by delegating to services and factoriesReason: Controller would be slimmer where implementation is hidden. Allows logic to be reused by multiple modules (specially by other controllers) and easier for unit testing
- Use one controller per view. If any logic needs to be reused, better to move it to a factory/service and use it from each separate controller
Reason: Controller will be slimmer, writing unit test will be simpler - Should use prototype to extend a controller and Object.create to create new object
- 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 (check this)
- Use this for public methods and variables as services are instantiated with the new keyword
- Consider creating a directive for any DOM manipulation. 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.
Reason: DOM manipulation can be difficult to test, debug - Use unique and short directive prefix
Reason: helps identify the directive's context and origin - Use restrict E for standalone element represented by the directive
- Use restrict A when the directive is enhancing a DOM element's attribute
- Avoid ng- as these are reserved for Angular directives
- Directives normalization
- Prefer using the dash-delimited format (e.g. ng-bind for ngBind). To use an HTML validating tool, data-prefixed version can be used (e.g. data-ng-bind for ngBind).
- Prefer using directives via tag name and attributes over comment and class names.
Reason: easier to determine what directives a given element matches - Directive creation
- Prefer using the definition object over returning a function
- prefix own directive names
Reason: to avoid any future collisions - Unless template is very small, it's typically better to break it apart into its own HTML file and load it with the templateUrl option
- Directives should clean up after themselves. Use $element.on('$destroy', ...) or $scope.$on('$destroy', ...) to run a clean-up function when the directive is removed
- use controller when want to expose an API to other directives. Otherwise use link.
- Use angular wrapper services. Like $document, $window, $timeout, $interval etc. instead of using native.
Reason: easily testable rather mocking native ones by yourself
Few Additional items: these items are more like personal preference. Though the Angular gurus (John Papa, Todd Motto) are more used to doing these or suggesting to do so.
- Consider separate line to inject dependencies rather in-line dependencies
Reason: long list of dependencies makes it harder to read. Little confusing as last item in the array is a function rather string value - Use ng-annotate for Gulp or Grunt and comment functions that need automated dependency injection using /* @ngInject */.
- Tool usage:
- Use Jasmine or Mocha for testing
- Use protractor for E2E (End to End) testing
- Use karma for test runner
- Use Sinon for stubbing and spying
- Use headless browser like PhantomJS
- Use JSHint as code analyzer
Resources:
1. https://github.com/johnpapa/angular-styleguide
2. https://github.com/toddmotto/angularjs-styleguide
3. http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript
4. http://www.johnpapa.net/angular-function-declarations-function-expressions-and-readable-code/
