mgechev / angularjs-style-guide

Introduction The goal of this style guide is to present a set of best practices and style guidelines for one AngularJS application. These best practices are collected from: • AngularJS source code • Source code or articles I've read • My own experience **Note 1**: this is still a draft of the style guide, its main goal is to be community-driven so filling the gaps will be greatly appreciated by the whole community. **Note 2**: before following any of the guidelines in the translations of the English document, make sure they are up-to date. The latest version of the AngularJS style guide is in the current document. In this style guide you won't find common guidelines for JavaScript development. Such can be found at: • Google's JavaScript style guide • Mozilla's JavaScript style guide • Douglas Crockford's JavaScript style guide • Airbnb JavaScript style guide • Idiomatic JavaScript style guide For AngularJS development recommended is the Google's JavaScript style guide. In AngularJS's GitHub wiki there is a similar section by ProLoser, you can check it here. Translations • German • Spanish • French • Indonesian • Italian • Japanese • Korean • Polish • Portuguese • Russian • Serbian • Serbian lat • Chinese • Turkish Table of content • General • Directory structure • Markup • Naming conventions • Others • Modules • Controllers • Directives • Filters • Services • Templates • Routing • E2E Testing • i18n • Performance • Contribution • Contributors General Directory structure Since a large AngularJS application has many components it's best to structure it in a directory hierarchy. There are two main approaches: • Creating high-level divisions by component types and lower-level divisions by functionality. In this way the directory structure will look like: • Creating high-level divisions by functionality and lower-level divisions by component types. Here is its layout: • In case the directory name contains multiple words, use lisp-case syntax: • Put all the files associated with the given directive (i.e. templates, CSS/SASS files, JavaScript) in a single folder. If you choose to use this style be consistent and use it everywhere along your project. This approach can be combined with both directory structures above. • The unit tests for a given component ( ) should be located in the directory where the component is. This way when you make changes to a given component finding its test is easy. The tests also act as documentation and show use cases. • The file should contain route definitions, configuration and/or manual bootstrap (if required). • Each JavaScript file should only hold **a single component**. The file should be named with the component's name. • Use AngularJS project structure template like Yeoman, ng-boilerplate. Conventions about component naming can be found in each component section. Markup TLDR; Put the scripts at the bottom. Keep things simple and put AngularJS specific directives after standard attributes. This will make it easier to skim your code and will make it easier to maintain because your attributes are consistently grouped and positioned. Other HTML attributes should follow the Code Guide's recommendation Naming conventions The following table is shown the naming conventions for every element: Element | Naming style | Example | usage ----|------|----|-------- Modules | lowerCamelCase | angularApp | Controllers | Functionality + 'Ctrl' | AdminCtrl | Directives | lowerCamelCase | userInfo | Filters | lowerCamelCase | userFilter | Services | UpperCamelCase | User | constructor Factories | lowerCamelCase | dataFactory | others Others • Use: • instead of • instead of • instead of • instead of • instead of • instead of or • instead of This will make your testing easier and in some cases prevent unexpected behaviour (for example, if you missed in ). • Automate your workflow using tools like: • NPM • Grunt • Gulp • Yeoman • Bower • Use promises ( ) instead of callbacks. It will make your code look more elegant and clean, and save you from callback hell. • Use instead of when possible. The higher level of abstraction will save you from redundancy. • Use an AngularJS pre-minifier (ng-annotate) for preventing problems after minification. • Don't use globals. Resolve all dependencies using Dependency Injection, this will prevent bugs and monkey patching when testing. • Avoid globals by using Grunt/Gulp to wrap your code in Immediately Invoked Function Expression (IIFE). You can use plugins like grunt-wrap or gulp-wrap for this purpose. Example (using Gulp) • Do not pollute your . Only add functions and variables that are being used in the templates. • Prefer the usage of controllers instead of . There are only a few appropriate uses of ngInit, such as for aliasing special properties of ngRepeat, and for injecting data via server side scripting. Besides these few cases, you should use controllers rather than ngInit to initialize values on a scope. The expression passed to should go through lexing, parsing and evaluation by the Angular interpreter implemented inside the service. This leads to: • Performance impact, because the interpreter is implemented in JavaScript • The caching of the parsed expressions inside the service doesn't make a lot of sense in most cases, since expressions are often evaluated only once • Is error-prone, since you're writing strings inside your templates, there's no syntax highlighting and further support by your editor • No run-time errors are thrown • Do not use prefix for the names of variables, properties and methods. This prefix is reserved for AngularJS usage. • Do not use inside your app, If you must, use instead with . • When resolving dependencies through the DI mechanism of AngularJS, sort the dependencies by their type - the built-in AngularJS dependencies should be first, followed by your custom ones: Modules • Modules should be named with lowerCamelCase. For indicating that module is submodule of module you can nes…