diff --git a/README.md b/README.md index 3a001fb2..e2f75d48 100644 --- a/README.md +++ b/README.md @@ -2,14 +2,14 @@ *Opinionated AngularJS style guide for teams by [@john_papa](//twitter.com/john_papa)* -If you are looking for an opinionated style guide for syntax, conventions, and structuring AngularJS applications, then step right in. These styles are based on my development experience with [AngularJS](//angularjs.org), presentations, [Pluralsight training courses](http://pluralsight.com/training/Authors/Details/john-papa) and working in teams. +If you are looking for an opinionated style guide for syntax, conventions, and structuring AngularJS applications, then step right in. These styles are based on my development experience with [AngularJS](//angularjs.org), presentations, [Pluralsight training courses](http://pluralsight.com/training/Authors/Details/john-papa) and working in teams. -The purpose of this style guide is to provide guidance on building AngularJS applications by showing the conventions I use and, more importantly, why I choose them. +The purpose of this style guide is to provide guidance on building AngularJS applications by showing the conventions I use and, more importantly, why I choose them. >If you like this guide, check out my [AngularJS Patterns: Clean Code](http://jpapa.me/ngclean) course at Pluralsight. [![AngularJs Patterns: Clean Code](https://raw.githubusercontent.com/johnpapa/angularjs-styleguide/master/assets/ng-clean-code-banner.png)](http://jpapa.me/ngclean) - + ## Community Awesomeness and Credit Never work in a vacuum. I find that the AngularJS community is an incredible group who are passionate about sharing experiences. As such, a friend and AngularJS 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](https://github.com/toddmotto/angularjs-styleguide) to get a sense for his approach and how it compares. @@ -18,7 +18,7 @@ Many of my styles have been from the many pair programming sessions [Ward Bell]( ## 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](https://github.com/johnpapa/ng-demos) in the `modular` folder. Feel free to grab it, clone it, or fork it. [Instructions on running it are in its readme](https://github.com/johnpapa/ng-demos/tree/master/modular). -##Translations +##Translations [Translations of this Angular style guide](https://github.com/johnpapa/angularjs-styleguide/tree/master/i18n) are maintained by the community and can be found here. ## Table of Contents @@ -42,7 +42,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see 1. [Startup Logic](#startup-logic) 1. [Angular $ Wrapper Services](#angular--wrapper-services) 1. [Testing](#testing) - 1. [Animations](#animations) + 1. [Animations](#animations) 1. [Comments](#comments) 1. [JSHint](#js-hint) 1. [Constants](#constants) @@ -56,7 +56,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ## Single Responsibility -### Rule of 1 +### Rule of 1 ###### [Style [Y001](#style-y001)] - Define 1 component per file. @@ -69,7 +69,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see .module('app', ['ngRoute']) .controller('SomeController', SomeController) .factory('someFactory', someFactory); - + function SomeController() { } function someFactory() { } @@ -103,7 +103,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see angular .module('app') .factory('someFactory', someFactory); - + function someFactory() { } ``` @@ -113,7 +113,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### JavaScript Closures ###### [Style [Y010](#style-y010)] - - Wrap AngularJS components in an Immediately Invoked Function Expression (IIFE). + - Wrap AngularJS components in an Immediately Invoked Function Expression (IIFE). *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. @@ -126,7 +126,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see .module('app') .factory('logger', logger); - // logger function is added as a global variable + // logger function is added as a global variable function logger() { } // storage.js @@ -134,15 +134,15 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see .module('app') .factory('storage', storage); - // storage function is added as a global variable + // storage function is added as a global variable function storage() { } ``` ```javascript /** - * recommended + * recommended * - * no globals are left behind + * no globals are left behind */ // logger.js @@ -168,7 +168,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see })(); ``` - - Note: For brevity only, the rest of the examples in this guide may omit the IIFE syntax. + - Note: For brevity only, the rest of the examples in this guide may omit the IIFE syntax. - 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. @@ -179,17 +179,17 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Avoid Naming Collisions ###### [Style [Y020](#style-y020)] - - Use unique naming conventions with separators for sub-modules. + - Use unique naming conventions with separators for sub-modules. - *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`. + *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`. ### Definitions (aka Setters) ###### [Style [Y021](#style-y021)] - - Declare modules without a variable using the setter syntax. + - Declare modules without a variable using the setter syntax. *Why?*: With 1 component per file, there is rarely a need to introduce a variable for the module. - + ```javascript /* avoid */ var app = angular.module('app', [ @@ -245,12 +245,12 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *Why?*: A module should only be created once, then retrieved from that point and after. - Use `angular.module('app', []);` to set a module. - - Use `angular.module('app');` to get a module. + - Use `angular.module('app');` to get a module. ### Named vs Anonymous Functions ###### [Style [Y024](#style-y024)] - - Use named functions instead of passing an anonymous function in as a callback. + - Use named functions instead of passing an anonymous function in as a callback. *Why?*: This produces more readable code, is much easier to debug, and reduces the amount of nested callback code. @@ -289,9 +289,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### controllerAs View Syntax ###### [Style [Y030](#style-y030)] - - Use the [`controllerAs`](http://www.johnpapa.net/do-you-like-your-angular-controllers-with-or-without-sugar/) syntax over the `classic controller with $scope` syntax. + - Use the [`controllerAs`](http://www.johnpapa.net/do-you-like-your-angular-controllers-with-or-without-sugar/) syntax over the `classic controller with $scope` syntax. - *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`. + *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`. *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". @@ -314,13 +314,13 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### controllerAs Controller Syntax ###### [Style [Y031](#style-y031)] - - Use the `controllerAs` syntax over the `classic controller with $scope` syntax. + - Use the `controllerAs` syntax over the `classic controller with $scope` syntax. - The `controllerAs` syntax uses `this` inside controllers which gets bound to `$scope` *Why?*: `controllerAs` is syntactic sugar over `$scope`. You can still bind to the View and still access `$scope` methods. - *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`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$emit), [`$broadcast`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$broadcast), or [`$on`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$on) consider moving these uses to a factory and invoke from the controller. + *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`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$emit), [`$broadcast`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$broadcast), or [`$on`](https://docs.angularjs.org/api/ng/type/$rootScope.Scope#$on) consider moving these uses to a factory and invoke from the controller. ```javascript /* avoid */ @@ -342,7 +342,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y032](#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. - + *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. ```javascript @@ -392,9 +392,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see - 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?*: 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. + *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. ```javascript /* avoid */ @@ -451,8 +451,8 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see vm.gotoSession = gotoSession; vm.refresh = function() { - /** - * lines + /** + * lines * of * code * affects @@ -489,11 +489,11 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *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 + *Why?*: Order is critical with function expressions ```javascript - /** - * avoid + /** + * avoid * Using function expressions. */ function Avengers(dataservice, logger) { @@ -601,7 +601,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see vm.isCreditOk; vm.total = 0; - function checkCredit() { + function checkCredit() { return creditService.isOrderTotalOk(vm.total) .then(function(isOk) { vm.isCreditOk = isOk; }) .catch(showServiceError); @@ -612,16 +612,16 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Keep Controllers Focused ###### [Style [Y037](#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. + - 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](#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. + - 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. + 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`](https://docs.angularjs.org/api/ng/directive/ngController), that view is always associated with the same controller. @@ -678,7 +678,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Singletons ###### [Style [Y040](#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. + - 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 AngularJS services are singletons](https://docs.angularjs.org/guide/services). This means that there is only one instance of a given service per injector. @@ -729,9 +729,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Accessible Members Up Top ###### [Style [Y052](#style-y052)] - - Expose the callable members of the service (it's interface) at the top, using a technique derived from the [Revealing Module Pattern](http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript). + - Expose the callable members of the service (it's interface) at the top, using a technique derived from the [Revealing Module Pattern](http://addyosmani.com/resources/essentialjsdesignpatterns/book/#revealingmodulepatternjavascript). - *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?*: 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. @@ -741,10 +741,10 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see /* avoid */ function dataService() { var someValue = ''; - function save() { + function save() { /* */ }; - function validate() { + function validate() { /* */ }; @@ -769,11 +769,11 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see //////////// - function save() { + function save() { /* */ }; - function validate() { + function validate() { /* */ }; } @@ -796,7 +796,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *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 + *Why?*: Order is critical with function expressions ```javascript /** @@ -926,7 +926,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see } } ``` - + Note: The data service is called from consumers, such as a controller, hiding the implementation from the consumers, as shown below. ```javascript @@ -958,7 +958,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see return vm.avengers; }); } - } + } ``` ### Return a Promise from Data Calls @@ -1012,9 +1012,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Limit 1 Per File ###### [Style [Y070](#style-y070)] - - Create one directive per file. Name the file for the directive. + - 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?*: 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. @@ -1071,7 +1071,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see /** * @desc spinner directive that can be used anywhere across the sales app at a company named Acme * @example
- */ + */ angular .module('sales.widgets') .directive('acmeSalesCustomerInfo', salesCustomerInfo); @@ -1103,7 +1103,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Manipulate DOM in a Directive ###### [Style [Y072](#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](https://docs.angularjs.org/api/ngAnimate), Angular templating, [`ngShow`](https://docs.angularjs.org/api/ng/directive/ngShow) or [`ngHide`](https://docs.angularjs.org/api/ng/directive/ngHide), then use those instead. For example, if the directive simply hides and shows, use ngHide/ngShow. + - 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](https://docs.angularjs.org/api/ngAnimate), Angular templating, [`ngShow`](https://docs.angularjs.org/api/ng/directive/ngShow) or [`ngHide`](https://docs.angularjs.org/api/ng/directive/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) @@ -1112,9 +1112,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see - Provide a short, unique and descriptive directive prefix such as `acmeSalesCustomerInfo` which is 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. + *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 AngularJS directives. Research widely used directives to avoid naming conflicts, such as `ion-` for the [Ionic Framework](http://ionicframework.com/). + Note: Avoid `ng-` as these are reserved for AngularJS directives. Research widely used directives to avoid naming conflicts, such as `ion-` for the [Ionic Framework](http://ionicframework.com/). ### Restrict to Elements and Attributes ###### [Style [Y074](#style-y074)] @@ -1157,7 +1157,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see
``` - + ```javascript /* recommended */ angular @@ -1185,7 +1185,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *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: 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](#manual-annotating-for-dependency-injection). @@ -1251,7 +1251,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *Why?*: It makes it easy to bind outer scope to the directive's controller scope. - Note: `bindToController` was introduced in Angular 1.3.0. + Note: `bindToController` was introduced in Angular 1.3.0. ```html
@@ -1270,9 +1270,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see max: '=' }, controller: ExampleController, - controllerAs: 'vm', - bindToController: true - }; + controllerAs: 'vm', + bindToController: true + }; return directive; } @@ -1300,13 +1300,13 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y080](#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](#style-y081) instead. - + ```javascript /* avoid */ function Avengers(dataservice) { @@ -1452,7 +1452,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y090](#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 AngularJS. ```javascript @@ -1476,19 +1476,19 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y091](#style-y091)] - Use `$inject` to manually identify your dependencies for AngularJS components. - + *Why?*: This technique mirrors the technique used by [`ng-annotate`](https://github.com/olov/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 AngularJS. - *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. + *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. ```javascript /* avoid */ angular .module('app') - .controller('Dashboard', - ['$location', '$routeParams', 'common', 'dataservice', + .controller('Dashboard', + ['$location', '$routeParams', 'common', 'dataservice', function Dashboard($location, $routeParams, common, dataservice) {} ]); ``` @@ -1497,9 +1497,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see /* avoid */ angular .module('app') - .controller('Dashboard', + .controller('Dashboard', ['$location', '$routeParams', 'common', 'dataservice', Dashboard]); - + function Dashboard($location, $routeParams, common, dataservice) { } ``` @@ -1516,7 +1516,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see } ``` - 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 either moving the $inject above the return statement or by using the alternate array injection syntax. + 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 either moving the $inject above the return statement or by using the alternate array injection syntax. Note: [`ng-annotate 0.10.0`](https://github.com/olov/ng-annotate) introduced a feature where it moves the `$inject` to where it is reachable. @@ -1583,10 +1583,10 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y100](#style-y100)] - Use [ng-annotate](//github.com/olov/ng-annotate) for [Gulp](http://gulpjs.com) or [Grunt](http://gruntjs.com) 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`](https://github.com/btford/ngmin) is deprecated + *Why?*: [`ng-min`](https://github.com/btford/ngmin) is deprecated >I prefer Gulp as I feel it is easier to write, to read, and to debug. @@ -1660,7 +1660,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y101](#style-y101)] - Use [gulp-ng-annotate](https://www.npmjs.org/package/gulp-ng-annotate) or [grunt-ng-annotate](https://www.npmjs.org/package/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 @@ -1694,7 +1694,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ###### [Style [Y110](#style-y110)] - Use a [decorator](https://docs.angularjs.org/api/auto/service/$provide#decorator), at config time using the [`$provide`](https://docs.angularjs.org/api/auto/service/$provide) service, on the [`$exceptionHandler`](https://docs.angularjs.org/api/ng/service/$exceptionHandler) service to perform custom actions when exceptions occur. - + *Why?*: Provides a consistent way to handle uncaught AngularJS 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. @@ -1716,9 +1716,9 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see function extendExceptionHandler($delegate, toastr) { return function(exception, cause) { $delegate(exception, cause); - var errorData = { - exception: exception, - cause: cause + var errorData = { + exception: exception, + cause: cause }; /** * Could add the error to a service's collection, @@ -1804,10 +1804,10 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see - 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. + *Why?*: The naming conventions should simply help you find your code faster and make it easier to understand. ### Feature File Names ###### [Style [Y121](#style-y121)] @@ -1820,7 +1820,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ```javascript /** - * common options + * common options */ // Controllers @@ -1849,7 +1849,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see // constants constants.js - + // module definition avengers.module.js @@ -1859,7 +1859,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see // configuration avengers.config.js - + // directives avenger-profile.directive.js avenger-profile.directive.spec.js @@ -1997,7 +1997,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Modules ###### [Style [Y127](#style-y127)] - - When there are multiple modules, the main module file is named `app.module.js` while other dependent modules are named after what they represent. For example, an admin module is named `admin.module.js`. The respective registered module names would be `app` and `admin`. + - When there are multiple modules, the main module file is named `app.module.js` while other dependent modules are named after what they represent. For example, an admin module is named `admin.module.js`. The respective registered module names would be `app` and `admin`. *Why?*: Provides consistency for multiple module apps, and for expanding to large applications. @@ -2015,7 +2015,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Routes ###### [Style [Y129](#style-y129)] - - Separate route configuration into its own file. Examples might be `app.route.js` for the main module and `admin.route.js` for the `admin` module. Even in smaller apps I prefer this separation from the rest of the configuration. + - Separate route configuration into its own file. Examples might be `app.route.js` for the main module and `admin.route.js` for the `admin` module. Even in smaller apps I prefer this separation from the rest of the configuration. **[Back to top](#table-of-contents)** @@ -2023,12 +2023,12 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### LIFT ###### [Style [Y140](#style-y140)] - - Structure your app such that you can `L`ocate your code quickly, `I`dentify the code at a glance, keep the `F`lattest structure you can, and `T`ry to stay DRY. The structure should follow these 4 basic guidelines. + - Structure your app such that you can `L`ocate your code quickly, `I`dentify the code at a glance, keep the `F`lattest structure you can, and `T`ry to stay DRY. The structure should follow these 4 basic guidelines. *Why LIFT?*: Provides a consistent structure that scales well, is modular, and makes it easier to increase developer efficiency by finding code quickly. Another way to check your app structure is to ask yourself: How quickly can you open and work in all of the related files for a feature? When I find my structure is not feeling comfortable, I go back and revisit these LIFT guidelines - + 1. `L`ocating our code is easy 2. `I`dentify code at a glance 3. `F`lat structure as long as we can @@ -2078,7 +2078,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see - Be DRY, but don't go nuts and sacrifice readability. - *Why?*: Being DRY is important, but not crucial if it sacrifices the others in LIFT, which is why I call it T-DRY. I don’t want to type session-view.html for a view because, well, it’s obviously a view. If it is not obvious or by convention, then I name it. + *Why?*: Being DRY is important, but not crucial if it sacrifices the others in LIFT, which is why I call it T-DRY. I don’t want to type session-view.html for a view because, well, it’s obviously a view. If it is not obvious or by convention, then I name it. **[Back to top](#table-of-contents)** @@ -2094,16 +2094,16 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ### Layout ###### [Style [Y151](#style-y151)] - - Place components that define the overall layout of the application in a folder named `layout`. These may include a shell view and controller may act as the container for the app, navigation, menus, content areas, and other regions. + - Place components that define the overall layout of the application in a folder named `layout`. These may include a shell view and controller may act as the container for the app, navigation, menus, content areas, and other regions. *Why?*: Organizes all layout in a single place re-used throughout the application. ### Folders-by-Feature Structure ###### [Style [Y152](#style-y152)] - - Create folders named for the feature they represent. When a folder grows to contain more than 7 files, start to consider creating a folder for them. Your threshold may be different, so adjust as needed. + - Create folders named for the feature they represent. When a folder grows to contain more than 7 files, start to consider creating a folder for them. Your threshold may be different, so adjust as needed. - *Why?*: A developer can locate the code, identify what each file represents at a glance, the structure is flat as can be, and there is no repetitive nor redundant names. + *Why?*: A developer can locate the code, identify what each file represents at a glance, the structure is flat as can be, and there is no repetitive nor redundant names. *Why?*: The LIFT guidelines are all covered. @@ -2154,12 +2154,12 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see Note: Do not use structuring using folders-by-type. This requires moving to multiple folders when working on a feature and gets unwieldy quickly as the app grows to 5, 10 or 25+ views and controllers (and other features), which makes it more difficult than folder-by-feature to locate files. ```javascript - /* + /* * avoid * Alternative folders-by-type. * I recommend "folders-by-feature", instead. */ - + app/ app.module.js app.config.js @@ -2190,7 +2190,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see speakers.html speaker-detail.html topnav.html - ``` + ``` **[Back to top](#table-of-contents)** @@ -2217,7 +2217,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *Why?*: Adding additional roles to the application root to get remote data, display views, or other logic not related to pulling the app together muddies the app module and make both sets of features harder to reuse or turn off. - *Why?*: The app module becomes a manifest that describes which modules help define the application. + *Why?*: The app module becomes a manifest that describes which modules help define the application. ### Feature Areas are Modules ###### [Style [Y163](#style-y163)] @@ -2228,7 +2228,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see *Why?*: Sprints or iterations can focus on feature areas and turn them on at the end of the sprint or iteration. - *Why?*: Separating feature areas into modules makes it easier to test the modules in isolation and reuse code. + *Why?*: Separating feature areas into modules makes it easier to test the modules in isolation and reuse code. ### Reusable Blocks are Modules ###### [Style [Y164](#style-y164)] @@ -2244,15 +2244,15 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see ![Modularity and Dependencies](https://raw.githubusercontent.com/johnpapa/angularjs-styleguide/master/assets/modularity-1.png) - *Why?*: The main app module contains a quickly identifiable manifest of the application's features. + *Why?*: The main app module contains a quickly identifiable manifest of the application's features. - *Why?*: Each feature area contains a manifest of what it depends on, so it can be pulled in as a dependency in other applications and still work. + *Why?*: Each feature area contains a manifest of what it depends on, so it can be pulled in as a dependency in other applications and still work. *Why?*: Intra-App features such as shared data services become easy to locate and share from within `app.core` (choose your favorite name for this module). Note: This is a strategy for consistency. There are many good options here. Choose one that is consistent, follows AngularJS's dependency rules, and is easy to maintain and scale. - > My structures vary slightly between projects but they all follow these guidelines for structure and modularity. The implementation may vary depending on the features and the team. In other words, don't get hung up on an exact like-for-like structure but do justify your structure using consistency, maintainability, and efficiency in mind. + > My structures vary slightly between projects but they all follow these guidelines for structure and modularity. The implementation may vary depending on the features and the team. In other words, don't get hung up on an exact like-for-like structure but do justify your structure using consistency, maintainability, and efficiency in mind. > In a small app, you can also consider putting all the shared dependencies in the app module where the feature modules have no direct dependencies. This makes it easier to maintain the smaller application, but makes it harder to reuse modules outside of this application. @@ -2272,7 +2272,7 @@ While this guide explains the *what*, *why* and *how*, I find it helpful to see .module('app') .config(configure); - configure.$inject = + configure.$inject = ['routerHelperProvider', 'exceptionHandlerProvider', 'toastr']; function configure (routerHelperProvider, exceptionHandlerProvider, toastr) { @@ -2398,14 +2398,14 @@ Unit testing helps maintain clean code, as such I included some of my recommenda - Use [PhantomJS](http://phantomjs.org/) to run your tests on a server. - *Why?*: PhantomJS is a headless browser that helps run your tests without needing a "visual" browser. So you do not have to install Chrome, Safari, IE, or other browsers on your server. + *Why?*: PhantomJS is a headless browser that helps run your tests without needing a "visual" browser. So you do not have to install Chrome, Safari, IE, or other browsers on your server. Note: You should still test on all browsers in your environment, as appropriate for your target audience. ### Code Analysis ###### [Style [Y195](#style-y195)] - - Run JSHint on your tests. + - Run JSHint on your tests. *Why?*: Tests are code. JSHint can help identify code quality issues that may cause the test to work improperly. @@ -2427,7 +2427,7 @@ Unit testing helps maintain clean code, as such I included some of my recommenda - Place unit test files (specs) side-by-side with your client code. Place specs that cover server integration or test multiple components in a separate `tests` folder. - *Why?*: Unit tests have a direct correlation to a specific component and file in source code. + *Why?*: Unit tests have a direct correlation to a specific component and file in source code. *Why?*: It is easier to keep them up to date since they are always in sight. When coding whether you do TDD or test during development or test after development, the specs are side-by-side and never out of sight nor mind, and thus more likely to be maintained which also helps maintain code coverage. @@ -2465,7 +2465,7 @@ Unit testing helps maintain clean code, as such I included some of my recommenda ### Sub Second ###### [Style [Y211](#style-y211)] - - Use short durations for animations. I generally start with 300ms and adjust until appropriate. + - Use short durations for animations. I generally start with 300ms and adjust until appropriate. *Why?*: Long animations can have the reverse affect on User Experience and perceived performance by giving the appearance of a slow application. @@ -2521,7 +2521,7 @@ Unit testing helps maintain clean code, as such I included some of my recommenda /** * @name logError * @desc Logs errors - * @param {String} msg Message to log + * @param {String} msg Message to log * @returns {String} * @memberOf Factories.Logger */ @@ -2635,7 +2635,7 @@ Unit testing helps maintain clean code, as such I included some of my recommenda .constant('moment', moment); })(); ``` - + ###### [Style [Y241](#style-y241)] - Use constants for values that do not change and do not come from another service. When constants are used only for a module that may be reused in multiple applications, place constants in a file per module named after the module. Until this is required, keep constants in the main module in a `constants.js` file. @@ -2644,7 +2644,7 @@ Unit testing helps maintain clean code, as such I included some of my recommenda *Why?*: Constants can be injected into any angular component, including providers. - *Why?*: When an application is separated into modules that may be reused in other applications, each stand-alone module should be able to operate on its own including any dependent constants. + *Why?*: When an application is separated into modules that may be reused in other applications, each stand-alone module should be able to operate on its own including any dependent constants. ```javascript // Constants used by the entire app @@ -2669,13 +2669,13 @@ Use file templates or snippets to help follow consistent styles and patterns. He ### Sublime Text ###### [Style [Y250](#style-y250)] - - AngularJS snippets that follow these styles and guidelines. + - AngularJS snippets that follow these styles and guidelines. - - Download the [Sublime Angular snippets](assets/sublime-angular-snippets.zip?raw=true) + - Download the [Sublime Angular snippets](assets/sublime-angular-snippets.zip?raw=true) - Place it in your Packages folder - - Restart Sublime + - Restart Sublime - In a JavaScript file type these commands followed by a `TAB` - + ```javascript ngcontroller // creates an Angular controller ngdirective // creates an Angular directive @@ -2697,7 +2697,7 @@ Use file templates or snippets to help follow consistent styles and patterns. He - AngularJS snippets and file templates that follow these styles and guidelines. You can import them into your WebStorm settings: - - Download the [WebStorm AngularJS file templates and snippets](assets/webstorm-angular-file-template.settings.jar?raw=true) + - Download the [WebStorm AngularJS file templates and snippets](assets/webstorm-angular-file-template.settings.jar?raw=true) - Open WebStorm and go to the `File` menu - Choose the `Import Settings` menu option - Select the file and click `OK` @@ -2793,7 +2793,7 @@ Open an issue first to discuss potential changes/additions. If you have question *By contributing to this repository you are agreeing to make your content available subject to the license of this repository.* ### Process - 1. Discuss the changes in a GitHub issue. + 1. Discuss the changes in a GitHub issue. 2. Open a Pull Request against the develop branch, reference the issue, and explain the change and why it adds value. 3. The Pull Request will be evaluated and either merged or declined. diff --git a/i18n/PT-BR.md b/i18n/PT-BR.md index befc0d49..0265901d 100644 --- a/i18n/PT-BR.md +++ b/i18n/PT-BR.md @@ -1642,15 +1642,14 @@ ou *Coletores de exceção* ``` ### Route Errors + - Gerencie e log todos os erros de routing utilizando o [`$routeChangeError`](https://docs.angularjs.org/api/ngRoute/service/$route#$routeChangeError). - - Handle and log all routing errors using [`$routeChangeError`](https://docs.angularjs.org/api/ngRoute/service/$route#$routeChangeError). - - *Why?*: Provides a consistent way 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. + *Por que?*: Fornece uma maneira consistente de gerenciar erros relacionados a routing. + + *Por que?*: Potencialmente fornece uma melhor experiência de usuário se um erro de routing ocorrer e você redirecionar o usuário para uma tela amigável com mais detalhes ou opções de recuperação. ```javascript - /* recommended */ + /* recomendado */ function handleRoutingErrors() { /** * Route cancellation: @@ -1674,18 +1673,18 @@ ou *Coletores de exceção* **[⬆ De volta ao topo ⬆](#tabela-de-conte%C3%BAdo)** -## Naming +## Nomenclatura -### Naming Guidelines +### Diretrizes de Nomenclatura - - 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. + - Use nomes consistentes para todos os componentes seguindo um padrão que descreve a funcionalidade do componente e (opcionalmente) seu tipo. Meu padrão recomendado é `característica.tipo.js`. Existem dois nomes para a maioria dos componentes: + * o nome do arquivo (`avengers.controllers.js`) + * o nome de componente registrado pelo Angular (`AvengersController`) - *Why?*: The naming conventions should simply help you find your code faster and make it easier to understand. + *Por que?*: As convenções de nomenclatura ajudam a fornecer uma maneira consistente de encontrar algo à primeira vista. Consistência dentro do projeto e vital. Consistência dentro de um time é importante. Consistência em toda a empresa proporciona uma enorme eficiência. + *Por que?*: As convenções de nomenclatura deveriam simplesmente te ajudar a encontrar trechos do seu código mais rápido e torná-lo mais fácil de se entender. + ### Feature File Names - 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`.