tldr; This style-guide is aimed at developers new to Angular
Declare named functions for controllers and other components.
angular
.module('app', [])
.controller('MainController', function MainController () {
});
Better:
angular
.module('app', [])
.controller('MainController', MainController);
function MainController () {
}
In general multi-line dot-chaining is more prone to error, but since we're also avoiding in-line call-backs, the issue should be greatly reduced and overall readability should remain high. This also follows what other style-guides suggest.
var app = angular.module('app', []);
app.controller('MainController', function() {
});
Better:
angular
.module('app', [])
.controller('MainController', MainController);
Use mapController
rather than map
. Use phoneService
rather than phone
Some style guides use UpperCamelCase such as DoAwesomeController
. This is primarily in preparation for ES6 and classes. While not absolutely necessary, being consistent about this keeps it clear.
function libraryController() { }
function authorDirective() { }
Better:
function LibraryController() { }
function AuthorDirective() { }
Use mapController
not mapCtrl
.
The syntax should be {feature}.{component}.js
or logger.service.js
, library.controller.js
.
Use these guidelines when introducing and working with directives.
In general DOM manipulations should be done in directives not controllers or services. This excludes built-ins such as ngShow
, ngHide
, angular animations and templates. CSS and animations can also be used independently.
This could conflict with newer versions.
Use these guidelines when introducing factories and services.
Use Services. Services and Factories are exceedingly similar and the differences are very tricky. We don't need to teach both. Services are closer to the way we teach controllers and should therefore be easier for developers. They also look similar to the way we teach constructors. 🌻
This does not conform with John Papa's styleguide. which recommends Factories over Services, but Services are more similar to our controller style. Just pick one and stay consistent!
// factory
function someFactory(){
var dataObj = {};
dataObj.doSomething = function(){
//...
}
return dataObj;
}
Better:
// service
function someService() {
this.doSomething = function(){
//…
}
}
Calling a Factory a Service or naming it someService
is confusing. The difference between the two is already quite confusing without mixing up the terminology.
Use these rules when working with MEAN or Rails+Angular stacks or anywhere else where you might encounter minification. They can be introduced after developers have gained some familiarity with Angular.
Use $inject
vs. inline annotation.
This has better readability and lower likelihood of syntax errors. Try to keep the $inject
call directly above the function it refers to. You can also align the functions parameters with the injected strings to make this more obvious.
angular
.module('app')
.controller('PhoneController', ['$location', '$routeParams', PhoneController]);
function PhoneController($location, $routeParams) {...}
Better:
angular
.module('app')
.controller('PhoneController', PhoneController);
PhoneController.$inject = ['$location', '$routeParams'];
function PhoneController($location, $routeParams) {...}
Or (if you're OCD):
// aligned
PhoneController.$inject = ['$location', '$routeParams'];
function PhoneController( $location, $routeParams ) {...}
For a comparison see the official angular tutorial
If you're following the above use of $inject
ng-annotate is unnecessary. However, you should consider using ng-strict-di
to alert you to missing annotations. Reference
Better:
<div ng-app="ngAppStrictDemo" ng-strict-di>