AngularJS Style Guide(gocardless.com)
gocardless.com
AngularJS Style Guide
https://gocardless.com/blog/angularjs-style-guide/
40 comments
Compare Rails and Django. Note that Django apps, which are meant to be made of stand-alone "apps", generally aren't - the apps end up relying on each other too much.
This seems to be because certain of what makes up each set of functionality "bleed" together - models, in particular, all seem to end up relying on each other.
I think the MVC / CDS, etc organizational structures are less about grouping things by feature and more about grouping things by common "bleed" factors (or, more likely, some deeper commonality that then causes the shared amount of "bleed"). Views pretty much never share anything. Controllers share utility functions. Models just go spaghetti.
You can also think of it like a toolbox; I keep all the screws together, rather than keeping all the flat-head screws with the flat-head screwdrivers.
That all said - Yeah, that's an excellent ideal, but it's not one that seems to occur in practice.
This seems to be because certain of what makes up each set of functionality "bleed" together - models, in particular, all seem to end up relying on each other.
I think the MVC / CDS, etc organizational structures are less about grouping things by feature and more about grouping things by common "bleed" factors (or, more likely, some deeper commonality that then causes the shared amount of "bleed"). Views pretty much never share anything. Controllers share utility functions. Models just go spaghetti.
You can also think of it like a toolbox; I keep all the screws together, rather than keeping all the flat-head screws with the flat-head screwdrivers.
That all said - Yeah, that's an excellent ideal, but it's not one that seems to occur in practice.
I'm coming back to JS development after several years away and my first impressions of Angular are that it seems very complicated and over-engineered, with a lot of fairly abstract concepts to digest to get even simple things working. React.js seems so much simpler but there does seem to be a lot of community support for Angular.
Should I invest the time and learn Angular or go with React instead? Web components seem likely to change the whole web development landscape but my impression is that they're not quite ready for prime time yet.
Should I invest the time and learn Angular or go with React instead? Web components seem likely to change the whole web development landscape but my impression is that they're not quite ready for prime time yet.
| Angular ... seems very complicated
Having recently picked up Angular, I can perhaps comment on this. Once you're past a few questions of where to put what, development with Angular is fairly straightforward. If you've dealt with two-way data binding before, it's even simpler.
I suspect you should be able to pick it up to a reasonable degree (one where you can decide if you'd like to stick with it) within a week or two at most, even in your spare time. In retrospect, I'm not sure I'd call it complicated any more.
Having recently picked up Angular, I can perhaps comment on this. Once you're past a few questions of where to put what, development with Angular is fairly straightforward. If you've dealt with two-way data binding before, it's even simpler.
I suspect you should be able to pick it up to a reasonable degree (one where you can decide if you'd like to stick with it) within a week or two at most, even in your spare time. In retrospect, I'm not sure I'd call it complicated any more.
That's reassuring. I look at some of the code examples and all the $vars and it looks very obscure. I guess the forthcoming 2.0 version is supposed to simplify things a lot and make it play nicely with web components though so maybe it's worth getting on board now.
To contrast with what the OP said, I found Angular pretty cool at the beginning but got more and more annoyed as I progressed. If you're okay with interacting with a black box, go for it otherwise choose react.
This is a distinct possibility, and I did run into one or two of these situations already. In my case, digging slightly into Angular's internals for workarounds was relatively successful.
An example is Angular's treatment of HTML forms and input elements, w.r.t. things that you'd expect, such as name / id interpolation (namely: Angular doesn't interpolate dynamic form names as you'd expect - [1] and [2]). In cases like this, digging into the internals to resolve the initial surprise and later solve the problem was slightly frustrating.
[1] https://github.com/angular/angular.js/issues/1404
[2] http://jsfiddle.net/Thinkscape/23RPt/
An example is Angular's treatment of HTML forms and input elements, w.r.t. things that you'd expect, such as name / id interpolation (namely: Angular doesn't interpolate dynamic form names as you'd expect - [1] and [2]). In cases like this, digging into the internals to resolve the initial surprise and later solve the problem was slightly frustrating.
[1] https://github.com/angular/angular.js/issues/1404
[2] http://jsfiddle.net/Thinkscape/23RPt/
From what I can tell of my experience, Angular is a library you can turn into a framework, by which I mean...
...It seems easy enough (given that I haven't actually taken something through what I'm about to suggest...) to go from zero independent JS - only using existing directives - smoothly and gradually into a full browser-side MVC. Start with directives, add some controllers, now a service or two and eventually some routing....
I also recently finished my first big feature using Angular, and am now ripping out most of the guts because I've realized that The Angular Way would let me do things drastically simpler. So I think there's some actual simplicity in how you can use it that may be hard to spot at first, or may not be apparent when you're coming from a different cognitive toolset (not that I know of anything other than Angular that I can for sure say has the same or a similar toolset...). As I grok it more, I like it more, but some stuff still gives me issue. I just don't use those parts until I understand, and then I delete the two-thirds of my code I don't actually need.
Also: I don't know ReactJS, so don't take this as a comparison to it in any way.
...It seems easy enough (given that I haven't actually taken something through what I'm about to suggest...) to go from zero independent JS - only using existing directives - smoothly and gradually into a full browser-side MVC. Start with directives, add some controllers, now a service or two and eventually some routing....
I also recently finished my first big feature using Angular, and am now ripping out most of the guts because I've realized that The Angular Way would let me do things drastically simpler. So I think there's some actual simplicity in how you can use it that may be hard to spot at first, or may not be apparent when you're coming from a different cognitive toolset (not that I know of anything other than Angular that I can for sure say has the same or a similar toolset...). As I grok it more, I like it more, but some stuff still gives me issue. I just don't use those parts until I understand, and then I delete the two-thirds of my code I don't actually need.
Also: I don't know ReactJS, so don't take this as a comparison to it in any way.
I had the pleasure of using Knockout.js on a recent project. It's so much simpler than Angular and a real pleasure to use.
It doesn't provide a complete opinionated framework like Angular. You have to pair it with the right 3rd party components to get a full SPA kit, but I like that better. I don't always need a full SPA either.
It doesn't provide a complete opinionated framework like Angular. You have to pair it with the right 3rd party components to get a full SPA kit, but I like that better. I don't always need a full SPA either.
Very helpful. I've unsuccessfully search for a way to do one-time binding before in a data intensive application and never came across the {{::ctrl.foobar}} syntax.
One thing I'm hesitant about is their advice to use directives instead of ng-controller="MyCtrl". Since controllers really are app specific glue code I rarely find myself wanting to reuse them - what advantages are directives supposed to give here?
One thing I'm hesitant about is their advice to use directives instead of ng-controller="MyCtrl". Since controllers really are app specific glue code I rarely find myself wanting to reuse them - what advantages are directives supposed to give here?
You can easily get one-time bindings using https://github.com/kseamon/fast-bind, which supports not only one-time bindings but also updating a binding only when called.
This makes it easy to work with data that doesn't change, promises, or large amounts of data that rarely changes.
Karl Seamon did a great talk about performance this past January at ng-conf as well, https://www.youtube.com/watch?v=zyYpHIOrk_Y
This makes it easy to work with data that doesn't change, promises, or large amounts of data that rarely changes.
Karl Seamon did a great talk about performance this past January at ng-conf as well, https://www.youtube.com/watch?v=zyYpHIOrk_Y
Yeah that was a great talk, definitely worth watching for those looking for ways to improve the performance of their Angular apps. Do you know of any other videos like that? I've searched in the past but haven't come up with much (especially not for stuff relevant to latest versions of Angular)
I haven't really found any videos as comprehensive as this, just blog posts or videos that discuss one topic/strategy at a time. Outside of this video, there doesn't seem to be an authoritative or even comprehensive list of what can be done to speed up applications.
As to newer stuff, I believe Karl is specifically talking about 1.2 (might of been a release candidate or beta at the time) so his talk should be applicable to the newest stable version, and I've found that to be true so far.
As an aside, and I haven't objectively measured it or even really investigated it, it seems angular's 1.x stable versions aren't coming out as fast as they once did (it feels like 1.3 has been in rc/beta forever and 2.0 doesn't even seem to be out of the planning stages). So at this point I think 1.3 stable will be released in the next few months and hopefully they will have an updated talk on performance at the next ng-conf in March.
As to newer stuff, I believe Karl is specifically talking about 1.2 (might of been a release candidate or beta at the time) so his talk should be applicable to the newest stable version, and I've found that to be true so far.
As an aside, and I haven't objectively measured it or even really investigated it, it seems angular's 1.x stable versions aren't coming out as fast as they once did (it feels like 1.3 has been in rc/beta forever and 2.0 doesn't even seem to be out of the planning stages). So at this point I think 1.3 stable will be released in the next few months and hopefully they will have an updated talk on performance at the next ng-conf in March.
Yeah unfortunately 1.3 drops support for IE8 which sadly makes it inappropriate for our production app for the time being. Which is a shame because it looks to have a tonne of performance fixes and bind-once built in which would have been nice, to avoid using a 3rd party module.
Directives are more powerful - for example, child directives can require the parent directive's controller and make use of it, which can lead to some powerful control flow.
You can also define a controller and have the directive consume it via named reference - here is one example that makes use of this: https://github.com/driftyco/ionic/blob/master/js/angular/dir...
Controllers should be consumed this way, so that they become easier to test. Testing directives can get complicated.
You can also define a controller and have the directive consume it via named reference - here is one example that makes use of this: https://github.com/driftyco/ionic/blob/master/js/angular/dir...
Controllers should be consumed this way, so that they become easier to test. Testing directives can get complicated.
One-time binding is a 1.3.0 beta feature (check your version before using)!
Anyone have experience one way or the other with the pattern of including test files with the features as opposed to under an alternate directory structure? I usually put tests and application code in parallel directories so that the tests are all in one place, but curious if anyone has seen big advantages one way or the other
I organise things the way you mentioned and was thinking this too. My app's starting to grow now and I think bundling tests, templates and the implementation in a single folder makes sense.
Normally if I'm working on eg a directive I jump across all of it's files, so having them in a single folder makes it much easier.
From a grunt/karma POV, it should be easy to flag specs as: \*.spec.js
Normally if I'm working on eg a directive I jump across all of it's files, so having them in a single folder makes it much easier.
From a grunt/karma POV, it should be easy to flag specs as: \*.spec.js
I do the same, mainly because I don't want to go through all the possible features folders to find the tests (I also put templates in a separate directory).
The advantage of grouping everything is you can just copy paste a feature and have everything needed in one go but I still find having separate directories simpler for me.
Todd Motto's angular style guide [1] has been one of the most helpful to me. It's always good to read multiple style guides and cherry-pick what works best for you :)
[1]: https://github.com/toddmotto/angularjs-styleguide
[1]: https://github.com/toddmotto/angularjs-styleguide
The recommendations in the module section are pretty awful - I'd avoid doing so, and every other expert in the community I've spoken to also disagree with that suggestion of using global functions wrapped in an IIFE to prevent it from being published on window, which seems to exclusively come out of Google.
What does IIFE stand for? From your I'm guessing it's an immediately evaluating function - but I can't figure the initialism out
What should be used instead?
What's so bad about it?
I find myself counter to the popular opinion on the use of controllerAs for mostly semantic reasons (IMO, a controller orchestrates services, $scope included, rather than containing data or references to data), though there are obvious and not-so-obvious tradeoffs with either choice.
That said, this style guide definitely has the strongest (almost convincing) argument I've seen for using controllerAs and does not have the inconsistencies I've found in other guides (`this` is not bound to `$scope` as a couple popular guides claim). Good stuff.
That said, this style guide definitely has the strongest (almost convincing) argument I've seen for using controllerAs and does not have the inconsistencies I've found in other guides (`this` is not bound to `$scope` as a couple popular guides claim). Good stuff.
Meh. NgAnnotate is way better than duplicating code. Be DRY, not pedantic.
Something we are looking to change. The duplication is pretty annoying, but we use AssetGraph-Builder for our production build, which uses ngmin, which doesn't play nice with ui-router. Also, now that 1.3 errors globally when you forget annotations, using NgAnnotate is much more of a no-brainer.
I have heard that it has trouble working in a complex build/development environment, e.g. when watching live file changes* with gulp/browserify.
*) https://www.npmjs.org/package/gulp-watchify/
*) https://www.npmjs.org/package/gulp-watchify/
Hmm. There are no open bugs for that on the gulp-ng-annotate or browserify-ngannotate repos. https://github.com/Kagami/gulp-ng-annotate/issues and https://github.com/omsmith/browserify-ngannotate/issues
Feel free to open issues and I'm sure it will be addressed.
ng-annotate itself just produces output for input (stdin/stdout or via files) so it does not at all have any trouble participating in a "complex build environment".
Feel free to open issues and I'm sure it will be addressed.
ng-annotate itself just produces output for input (stdin/stdout or via files) so it does not at all have any trouble participating in a "complex build environment".
A minor nit, the TL;DR is just an outline. I was hoping for a simple statement of the problem with a conclusion and the rest of the article would present the details, more of a real overview or synopsis.
> We would, for example, pick verbose over DRY if that results in code that’s easier to read and change. We have found that inheritance and mixins make change especially hard.
I disagree. We have a mixin heavy product (about 100k LOC) and the mixins, if designed judiciously, help ensure that we have good reuse of code. So I'd like to see some examples to support the case of "verbose over DRY", I haven't yet found that to be a "good thing(tm)", but some concrete examples could help.
I disagree. We have a mixin heavy product (about 100k LOC) and the mixins, if designed judiciously, help ensure that we have good reuse of code. So I'd like to see some examples to support the case of "verbose over DRY", I haven't yet found that to be a "good thing(tm)", but some concrete examples could help.
I got a lot out of this. I’ve never worked in a platform that evolves as rapidly as Angular, and have found myself blinded by “last year’s advice” a few times. Quite a bit of modern thinking here.
logically this should come from Google (the author of AngularJS)... anyway, thanks, I'll definitely try to use it
Is this article an ad?
Isn't every blog post an ad of some description? Company blogs are designed to drum up interest in the product / service being offered. However, I'd say this post been written to advertise the style-guide they've open-sourced more than anything.
The actual post title is: "The GoCardless AngularJS Style Guide". I was expecting something about how they needed to do XYZ to make Angular run well rather than how they scale up development.
We changed the title to that (minus the domain name, as the HN guidelines ask). It used to be "Scaling AngularJS at GoCardless".
My idea of a good modular file structure is that you could delete any random directory and delete it and it would lop off that feature as cleanly as possible. Each directory should represent an angular module, and each module should contain the routing, controllers, services, directives, and tests that it uses. If some of these are used across the app then you can have a "common" module.