{"id":34730913,"url":"https://github.com/tgaff/angular_style_guide","last_synced_at":"2026-01-20T17:03:00.753Z","repository":{"id":72693583,"uuid":"50940331","full_name":"tgaff/angular_style_guide","owner":"tgaff","description":"style conventions for teaching angular","archived":false,"fork":false,"pushed_at":"2016-02-09T04:09:31.000Z","size":9,"stargazers_count":0,"open_issues_count":3,"forks_count":9,"subscribers_count":1,"default_branch":"master","last_synced_at":"2023-08-03T07:12:17.656Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tgaff.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-02T18:02:05.000Z","updated_at":"2016-02-02T18:02:05.000Z","dependencies_parsed_at":"2023-04-29T14:07:36.531Z","dependency_job_id":null,"html_url":"https://github.com/tgaff/angular_style_guide","commit_stats":null,"previous_names":[],"tags_count":0,"template":null,"template_full_name":null,"purl":"pkg:github/tgaff/angular_style_guide","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgaff%2Fangular_style_guide","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgaff%2Fangular_style_guide/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgaff%2Fangular_style_guide/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgaff%2Fangular_style_guide/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tgaff","download_url":"https://codeload.github.com/tgaff/angular_style_guide/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tgaff%2Fangular_style_guide/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-12-25T02:57:17.707Z","updated_at":"2026-01-20T17:03:00.744Z","avatar_url":"https://github.com/tgaff.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Purpose\n\nThere are many good styleguides already available for Angular: [here](https://github.com/toddmotto/angular-styleguide) and [here](https://github.com/johnpapa/angular-styleguide)  So, why do we need another one?\n\nThis styleguide is different in that it is focused on teaching \u0026 learning Angular.  The syntax and structures advocated by other styleguides are great if you're already an Angular guru with plenty of experience, but can be extremely difficult for students new to Angular, with varying levels of JS knowledge to understand.  When we teach we generally increase complexity over time.  This guide aims to set guidelines to ensure that syntax across lessons is the same, while slowly introducing additional syntactical complexity.\n\n**tldr; This style-guide is aimed at students new to Angular, not angular professionals.**\n\n# Immediate Guidelines:\nThese guidelines are suggested for all code given to students.  \n\n### prefix data- on attributes and directives\n\nUse `data-` prefixed attributes instead of raw angular attributes/directives.  These pass HTML validators.\n\nAvoid:\n```html\n \u003cdiv ng-controller=\"MainController\"\u003e\n```\nRecommended:\n```html\n \u003cdiv data-ng-controller=\"MainController\"\u003e\n```\n\n### controller as syntax\n\nUse Controller as syntax, which promotes the demystifying use of dot syntax in HTML to indicate where variables come from.  This also means it is possible to safely use scalars on the controller.  You must also avoid the use of `$scope` and use `this` instead in your controllers.\n\nAvoid:\n```html\n\u003cdiv ng-controller=\"CustomerController\"\u003e\n    {{ name }}\n\u003c/div\u003e\n```\n\nRecommended:\n```html\n\u003cdiv ng-controller=\"CustomerController as customer\"\u003e\n    {{ customer.name }}\n\u003c/div\u003e\n```\n\n### define named functions for each component\nDeclare named functions for controllers and other components.\n\nAvoid:\n```js\nangular\n  .module('app', [])\n  .controller('MainController', function MainController () {\n\n  })\n  .service('SomeFactory', function SomeFactory () {\n\n  });\n```\n\nRecommended:\n```js\nangular\n  .module('app', [])\n  .controller('MainCtrl', MainCtrl)\n  .factory('SomeFactory', SomeFactory);\n\n\nfunction MainController () {\n\n}\nfunction SomeFactory () {\n\n}\n ```\n\n### use dot chaining to build the app rather than repetition of an app variable\nIn 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.\n\nAvoid:\n```js\nvar app = angular.module('app', []);\napp.controller('MainController', function() {\n});\napp.factory('SomeFactory', function() {\n});\n```\n\nRecommended:\n```js\nangular\n  .module('app', [])\n  .controller('MainController', MainController)\n  .factory('SomeFactory', SomeFactory);\n```\n\n\n\n\n\u003c!-- NAMING --\u003e\n# Naming\n\n### Suffix should identify the type of module.\n\nUse `mapController` rather than `map`. Use `phoneService` rather than `phone`\n\n### Use camel case for controllers, directives, etc.\n\nSome style guides use DromedaryCase or UpperCamelCase such as `DoAwesomeController`.  This is primarily in preparation for ES6 and classes.  Students can use the syntax they're already used to.\n\nAvoid:\n```\nfunction LibraryController() { }\n```\n\nPrefer:\n```\nfunction libraryController() { }\n```\n### use long-form names for controllers and other components\n\nUse `mapController` not `mapCtrl`.\n\n### Filenames identify component separated by `.`\n\nThe syntax should be `{feature}.{component}.js` or `logger.service.js`, `library.controller.js`.\n\n\n\n\n\n\n\u003c!-- DIRECTIVES --\u003e\n# When talking about directives\nUse these guidelines when introducing and working with directives.\n\n### Directives not controllers should manipulate the DOM.\n\nIn 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.\n\n### Controller-as in Directives\n\nRemember to specify `controllerAs` in directives.  It's also extremely common to use `vm` as the name in this case.\n\nAvoid:\n```js\nfunction dragUpload () {\n  return {\n    controller: function ($scope) {\n\n    }\n  };\n}\nangular\n  .module('app')\n  .directive('dragUpload', dragUpload);\n```\nPrefer:\n```js\nfunction dragUpload () {\n  return {\n    controllerAs: 'vm',\n    controller: function () {\n\n    }\n  };\n}\nangular\n  .module('app')\n  .directive('dragUpload', dragUpload);\n```\n\n[code from](https://github.com/toddmotto/angular-styleguide#directives)\n\n### Don't ng-* prefix directives.\n\nThis could conflict with newer versions.\n\nAvoid:\n```js\n\u003cdiv ng-upload\u003e\n```\n\nPrefer:\n```\n\u003cdiv drag-upload\u003e\n```\n\n\n# When working with factories and services\nUse these guidelines when introducing factories and services.\n\n### Factories vs. Services\n\nUse Factories.  This conforms with [John Papa's styleguide](https://github.com/johnpapa/angular-styleguide#style-y040).  \nServices and Factories are exceedingly similar and the differences are very tricky.  We don't need to teach both.\n\n\u003e It should be noted that Services are closer to the way we teach controllers and might therefore be easier for students.  An argument could be made for flipping this rule as long as it's done consistently.  \n\nService Pattern - Avoid:\n\n```js\nfunction someService(){\n\tthis.doSomething = function(){\n\t\t//…\n\t}\n}\n```\n\nFactory Pattern - Prefer:\n```js\nfunction someFactory(){\n\tvar dataObj = {};\n\tdataObj.doSomething = function(){\n\t\t//...\n\t}\n\treturn dataObj;\n}\n```\n\n### Do not call Factories services\n\nCalling a Factory a Service or naming it `someService` is confusing.  The difference between the two is already [quite](http://stackoverflow.com/questions/14324451/angular-service-vs-angular-factory) [confusing](http://stackoverflow.com/questions/16596569/angularjs-what-is-a-factory) without mixing up the terminology.\n\n\n# When introducing minification\nUse these rules when working with MEAN or Rails+Angular stacks or anywhere else where you might encounter minification.  They can be introduced after students have gained some familiarity with Angular.\n\n### Use $inject vs. inline annotation for dependency injection\n\nUse $inject vs. inline annotation.  \n\nThis has better readability and lower likelihood of syntax errors.  Try to keep the `$inject` call near the function it refers to.\n\nAvoid:\n```js\nangular\n  .module('app')\n  .controller('PhoneController', ['$location', '$routeParams', PhoneController]);\n\nfunction PhoneController($location, $routeParams) {...}\n```\nPrefer:\n```js\nangular\n  .module('app')\n  .controller('PhoneController', PhoneController);\n\nPhoneController.$inject = ['$location', '$routeParams'];\nfunction PhoneController($location, $routeParams) {...}\n```\n\n\u003e For a comparison see the [official angular tutorial](https://docs.angularjs.org/tutorial/step_05)\n\n### Use gulp or grunt with MEAN stack, use asset-pipeline with Rails.\n\nIf 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](https://docs.angularjs.org/api/ng/directive/ngApp)\n\nPrefer:\n```js\n\u003cdiv ng-app=\"ngAppStrictDemo\" ng-strict-di\u003e\n```\n\n\n\n\n# Introduce eventually\nThese rules should be mentioned at some point, but not right away.\n\n### mention (but don't use) $scope in controllers\n\nSince we're using controller-as and `this` in our controllers, `$scope` will only rarely be used.  However, students are going to come across blogs, older code and stackoverflow posts that use `$scope` frequently.  We should mention how this works, at least in writing, but not right away.\n\n\u003e Note: when using $scope one should always pass objects, not scalars.\n\u003e Use `$scope.obj = {}` rather than `$scope.foo = 'adsf'`\n\n### capture `this` in a `vm` or other variable in controllers\n\nContext of `this` could be changed in a function within a controller.  Capturing in another name avoids this issue.  Note how this rule works with controller-as.  \n\nAvoid:\n```js\nfunction PostsController() {\n    this.title = 'Some Title';\n}\n```\nPrefer:\n```js\nfunction PostsController() {\n    var vm = this;\n    vm.title = 'Some Title';\n}\n```\n\u003e Note: We could use this rule immediately with likely little additional trouble. [discuss](https://github.com/tgaff/angular_style_guide/issues/2)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgaff%2Fangular_style_guide","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftgaff%2Fangular_style_guide","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftgaff%2Fangular_style_guide/lists"}