Angular Style Guide | John Papa

John Papa

Evangelist on the loose

Angular Style Guide

...

angular-icon I just published the first draft of my opinionated style guide for syntax, conventions, and structuring AngularJS applications. You’ll find many of these and more explained in deeper detail in my Pluralsight course AngularJS: Clean Code (coming in August 2014). The styles contained here are based on on my experience with AngularJS, presentations, Pluralsight training courses and working in teams. I will keep this guide updated on github.

Usage and Purpose

I get asked a lot for style guides, how to get started once you learn the AngularJS basics, and what I recommend. This guide helps point in that direction using my guidelines. 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. That last part is important … it’s is not important to follow someone else’s guidelines (including mine) as much as it is to understand why people choose what they do. I tried to share my reasons in this document to shed some light on how I think about the challenges and solutions. This has always helped me, and I hope it helps you.

What this Guide is Not

This guide is not intended to serve as a demo of reusable code, code snippets, or advanced solutions though it may drop a few here or there. Rather it is intended to be a starting point for a team looking for consistency.

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 to get a sense for his approach and how it compares.

Many of my styles have been from the many pair programming sessions Ward Bell and I have had. While we don’t always agree, my friend Ward’s has certainly helped influence the ultimate evolution of this guide.

What’s Included

Here is a starting list of what is included, with more to come.

There is much more in the AngularJS Style Guide, which I will continue to update and add content to.

  1. Single Responsibility
  2. Modules
  3. Controllers
  4. Services
  5. Factories
  6. Directives
  7. Resolving Promises for a Controller
  8. Manual Dependency Injection
  9. Minification and Annotation
  10. Exception Handling
  11. Naming
  12. Application Structure
  13. Modularity
  14. Angular $ Wrapper Services
  15. Comments

Contributing

If you have questions with the guide, feel free to leave them as issues in the repo. If you find a typo, create a pull request. The idea is to keep the content up to date and use github’s native feature to help tell the story with issues and PR’s, which are all searchable via google. Why? Because odds are if you have a questions, someone else does too! You can learn more here at about how to contribute.

tags: angular javascript open source patterns pluralsight
  • http://sampathloku.blogspot.com/ Sampath Lokuge

    Awesome John.Thanks a lot for sharing.Keep up the great work. :)

  • http://www.thisxboxlife.com/ Brun J. Swick

    Thanks! Can’t wait for the course in August!

  • http://www.fizzylogic.nl/ Willem Meints

    This is a great idea. I have been looking around for styleguides like this one. You could say this is a mere styleguide. I actually like to think of them as a best-practices book that you can pick up and read to get a sense of what the best setup for a particular piece of code would look like.

  • Pingback: Angular Style Guide | IT News | Scoop.it

  • Phil

    Off point question, do you have any stat on the usage comparison of angular vs knockout vs ember?

  • glendaviesnz

    Thanks, this is really helpful – just one questions, with the ‘single responsibility’ setup and each component of a module in its own file how do you recommend structuring your include/build/concat process to ensure that files are loaded/complied in the correct order? A bit of discussion here about this https://github.com/ngbp/ngbp/issues/152 in relation to the ngbp angular boilerplate which breaks if you split out module components into separate files.

    • johnpapa7

      Easiest way I use is to name all modules with a pattern, then I can do this to ensure modules are loaded first, and all other angular files after those:

      “../client/app/**/*module*.js”,
      “../client/app/**/*.js”

  • Pingback: The Morning Brew - Chris Alcock » The Morning Brew #1662

  • http://www.beintrepid.co.uk Alexander Preston

    Great stuff John – getting stuck in now :-)

  • Prasad Honrao

    This is great stuff John and thanks a lot for it. BTW, I know which Pluralsight course is going to be on #1 position in Aug. :)

  • Pingback: Angular Style Guide | Nova Tech Consulting | S...

  • Tyler Lesperance

    Love it. Currently working on a large Angular project and have had to really think about consistent styles throughout. A lot of this stuff is what I’ve been using in this application and have found to be easy to read and use, and after reading this over, I can see how implementing the rest will only make things better.

  • Eric

    You slick son of a gun.

    Favorite part here: Dashboard.$inject = ['$location', '$routeParams', 'common', 'dataservice'];

    Never knew it existed! When is this coming to PluralSight, any concrete date in August?

  • Mike Sigsworth

    Can you expand on your recommendations in “Resolving promises for a controller”?

    Within that section you first recommend using an activate() method (which is how you do it in Code Camper). Yet within the activate method you are relying on a promise, which in the following recommendation you say should be resolved via the route config.

    Aren’t the two parts in that recommendation mutually exclusive? Is there a subtle difference I’m not seeing?

    Thanks!

    • johnpapa7

      @mikesigsworth:disqus Sure. When you need a promise to resolve before the controller loads, use a route resolver. When you need the data as the controller loads, use activate. The resolver allows you to cancel the route change, while in activate its too late.

      • Patrick Leblanc

        @johnpapa7:disqus How would handle nicely a $q.reject in the route resolver? the code could become quite heavy in the resolve section. Would you create a factory to handle all the preloading?

  • Vladislav Kasirski

    http://cc-ng-z.azurewebsites.net/ has a bug. If you close the menu in the narrow variant of the site, when you widen it, the menu is no longer there and there is no way to get it.

  • Pingback: Andrey on .NET | Интересности #43

  • Oron Ben Zvi

    too bad unit testing isn’t mentioned here.

  • Pingback: Links of the month (July Edition) | Jan @ Development

  • Patrick Leblanc

    I just wanted to say your angular styling guide is absolutely phenomenal and helped me and my team to have an in depth understanding of angular and its philosophy that is, in my opinion, getting drowned in a sea of bad examples around the web.

    Thank you so much.

  • Francesco Pipita

    Hello John, thank you so much for your amazing guide.

    I got a question for you: according to your experience, are core/common concerns best organized by feature, file type or anything else?

    Thanks!

    • johnpapa7

      My recommendation is by feature.

  • jbrodriguez2

    this is great stuff and i’m basing my code on this guide.

    something i’ve not seen mentioned is shared components.

    for example, using the folder-by-feature structure, my app has some features that share a common template view … so that’s no problem, i created a shared folder and link there for the template view.

    but the problem comes from the controllers, since each feature has a different controller, i’m having to replicate functions in each of the controllers to handle common operations on the data.

    can you suggest an alternative way of doing this ?

    • John

      I’m not following your example. Can you show an example in a gist?

  • Vincent Zhang

    Thank you so much for your great article!

    I have a question about ‘Constants’ section. Do you mean that we should put the declarations of toastr & moment at the top of constants.js or somewhere in other .js files like:

    window.toastr = false;
    window.moment = false;

    Thank you!

  • cbfranca

    Hello John, great guidelines, but i’ve one doubt. In my controller’s directive when i need to use $emit to controller that it’s listening, is it possible capture $on with ‘this’ in controllerAs syntax ?

%d bloggers like this: