Things that suck in AngularJS | Hacker News Reader

Things that suck in AngularJS

lhorie.blogspot.ca

219 pointssbarre148 comments

Documentation is by far the worst part of Angular. I spent 90% of my time Googling and 10% writing code. (Hey, maybe that's Google's plan -- ramp up traffic to search. Synergy!)

AngularUI is confusing, mostly undocumented and often behind Angular. Splitting ngRoute/ngAnimate into their own files is an odd choice, although I assume the former is so they can replace it with the superior ui-router. Which also is weird. Like jQuery, it seems like the UI portion is just off on their own doing what they want.

Google has the chance to build the new framework that will run the web in 2-3 years. Much like Rails a few years ago. Angular is an amazing framework. It seems like they just don't care.

Angular needs someone versed in developer usability to take control of the public facing Angular stuff and give it a complete overhaul. Right now, it's the result of hundreds of people haphazardly making changes.

Is there a Javascript MVC framework that actually has good documentation, guides, and code samples? I've been working with Ember.js, but it's incredibly frustrating trying to learn a framework whose documentation is incomplete.

The other problem I've found is that docs, tutorials, and Stack Overflow posts that are even six months old are often completely useless when troubleshooting bugs in Ember.js or even learning its basic features.

It seems Angular suffers from the same complaints I have about Ember.js. Those of us who really need to just "get things done" might be better suited by a mature, well-documented framework, but does one actually exist?

I felt like Backbone.js (when I was actively using it) had really clean and complete docs. Couple that with the fact that the source is incredibly readable and debugging anything strange was never that tough.

Sure, but Backbone does a fraction of what Angular does. And, it's pretty consistent with how most people write JS anyway -- whereas Angular pretty much re-envisioned everything.

You say that like it's a pro but I'm pretty sure it's a con.

It depends on your point of view. Personally I've never been too happy about the state of JS code, so trying something different is absolutely a good thing.

Is Angular the best approach? Is there even such a thing as a best approach? Probably not. Look at the proliferation of server side frameworks. They each have their pros and cons.

I do like that Angular is a real framework, rather than a library that only gets called a framework. It handles all sorts of stuff for you in the same way serverside frameworks tend to do.

whereas Angular pretty much re-envisioned everything.

Angular is the first time I've written a web-app and been completely lost from second one without a fully stateful JavaScript debugger willing to break at any point and letting me inspect the call-stack, parameters and locals.

Everything which was simple about the web up until now, Angular transformed into horrible, black voodoo magic which either just worked or didn't at all.

If that's what "re-envisioned everything" is all about, consider me out.

To each their own, I guess. I've rewritten numerous apps in a fraction of the original time (and original line count) using Angular. There's a bit of a learning curve, but once I started "thinking Angular" (aka, if you're touching the DOM you're doing it wrong), it was great.

> Everything which was simple transformed into horrible, black voodoo magic

That's what radical re-envisionings always look like. Anything that fits easily into your toolbelt is an incremental improvement. That's what the word "radical" means.

The promise is that after doing some hard work to learn new data structures you will be more powerful, but it's certainly your right to be skeptical of that.

I started with Ember about a year ago and the getting started docs were pretty terrible. It took a lot of experimentation and frustration before I was comfortable developing with it. Eventually I became familiar with the framework and the API docs are quite in-depth, not really great for a beginner though. After about four Ember projects I can now prototype a large app (using something like Bootstrap) in a day or so, so I feel that pain at the start was worth it. Back at the time though I was tearing my hair out, especially over router changes. The changes improved things by an order of magnitude though. I trust the Ember team, I'm happy now, the start could have been easier.

My experience pretty much parallels yours. These frameworks are at the cutting edge. Only a handful of big apps have been made with Ember or Angular, and so the core teams are constantly bumping up against weaknesses in their designs which can only be addressed by making changes that break apps.

From reading the Ember discussion lists I get the strong sense that the core team is willing to make difficult breaks, but that they really try to only do it when it's absolutely necessary for the long-term robustness of the platform. A lot of thought seems to go into which problems are getting solved now, which are put off til later, and which interfaces get torn out and rewritten.

I just spent several weeks upgrading my app from the earlier Ember RCs to Ember 1.0 and the latest Ember-data, and while quite painful, I feel good about it because I don't think the core team made those changes lightly. My sense is they are looking out for us.

I'm currently working on a big Angular app that is about to move into production (although it's not to be something that's widely used in public) - we have found that Angular causes everything to be structured in a nicely organized fashion overall. This app is not structured perfectly by any means either, due to bad design on some of our pre-existing code base.

From what I understand, big Ember projects have turned out well for Ember devs - I can confidently say that I feel the same way about big Angular apps. I have built several big ones, including an online assessment platform (frontend by myself) and an online assessment platform/management system (with a team of ~10, 3 of us on frontend).

From my experience, the Angular team has thought things out on a high level, which I greatly appreciate. They are big consumers of their own product, as Angular is used quite a bit with Google's own sites - here is an example of an Angular app, with Angular being used to implement parallax scrolling (and probably more): http://www.google.com/nexus/7/

> Those of us who really need to just "get things done" might be better suited by a mature, well-documented framework, but does one actually exist?

No.

Frameworks are all the same in that they are great at getting you to about 80% of what you need REALLY fast. The next 10% takes some investigation but its doable.

But that last 10%. Its like pulling teeth. You're working for the framework rather than it working for you. In my experience, all of the time gains you realize from using a framework early on are lost (and then some) trying to get it to do that last 10% that you need.

Ultimately I've found that using vanilla Javascript offers everything I need to just "get things done" and complete a project successfully. Sure, I might not be able to get something out the door in a day. But at the end of the project I've delivered clean, maintainable code on time. And anyone who knows Javascript will be able to read it.

Now, lest you think I'm a complete framework hater; they have their place. They're great at prototyping, for example. But never again will I build an entire project on one. I have little interest in being a glorified glue stick, piecing framework code together. How boring.

I should add that I make heavy use of libraries like jQuery and Underscore. They're libraries, not frameworks. Take what you need with them yet still reasonably lightweight. Frameworks are bloated, tightly-coupled, poorly documented monstrosities in my opinion.

Finally someone said it. Even if I write more code by only using libraries and no frameworks (which is debatable), at least I'm happy while writing it.

I do consider some frameworks to be exceptions though. Express is called a framework but it looks more like a library for HTTP handling to me. Most npm packages behave like libraries - maybe that's why I like using Node.js so much. Also CSS "frameworks" like Bootstrap aren't in the same league. They've never caused me the type of frustration I've had with frameworks like RoR or Angular. Bootstrap is actually a library of UI widgets. They can call it a "framework" but I don't consider it to be one.

I think it depends on how good you are. If you're a great developer, with deep knowledge of patterns, a strong commitment to refactoring, with lots of experience such that you're aware of the pitfalls you are likely to befall, then you're probably right: frameworks will buy you little.

I'm pretty good, but I'm apparently not good enough, because I find myself consistently learning things from frameworks. I certainly am familiar with the Last Ten Percent you're talking of. But I also know that for every 10% that I have to pull teeth to get, there are many many things that work well because the platform team did a great job and drew on a depth of experience and expertise that I just don't have yet.

DHH built a lot of Ruby apps before he built Rails, and by using Rails I can draw on his experience. As a solo founder that's worth a lot to me. And even now, when I've largely moved on from Rails I still draw on things I learned from studying that framework. And the frameworks I use now are equal distillations of very deep experience.

You're perhaps a more experienced developer than I am, or just better suited to the job.

You touch on one of the other benefits of a framework; they're a fairly decent way to learn. But, unfortunately, much of that is because you're learning what NOT to do.

A much better way to learn is to go write your own framework. Then you're forced to encounter the pitfalls and overcome them through research, trial-and-error, and interacting with the community.

But continuing to use a framework is just a crutch in my opinion. At some point not only are you not learning anything but, as I mentioned before, all you're really doing is gluing framework code/modules together. You're actively doing yourself a disservice and letting your skills atrophy by relying on such a crutch.

One thing about frameworks that I find interesting is; how many were used to develop Unix? None. Because there weren't any back then. And now its in billions of devices worldwide.

I did this myself. It was crap. Fun to write, and I learned a lot from it. But still, monolithic, poorly documented, tightly-coupled crap and even I don't use it anymore.

Does anyone have experience with Enyo (the framework from WebOS)?

It claims to be adding MVC support in the next release.

Check out KnockoutJS, I've found their documentation to be quite good and it's a pretty easy framework to learn.

KnockoutJS.com is by far the best in terms of documentation and usability for novices.

I agree that the documentation could be better. When I first started working with Angular I had similar issues. However, after spending a decent amount of time working with the framework, I find the documentation fairly clear. The problem is really the lack of concrete examples of how things fit together.

However, Angular UI is a totally separate set of projects that is not run by the Angular team at all. Not sure why you're giving them a hard time about it.

I think the documentation has improved. I think the Developer Guide provides a good high level. Perhaps some opinionated best practises & design patterns would help.

And yea, Angular UI is awesome.

With this many people saying the documentation could be improved, is there a reason holding everyone back from contributing or improving it?

The irony is that not only is there a commenting system to complain about the docs, but that at the top of most of the pages is a prominent "Improve this doc" button, which when clicked, takes you directly to the file in Github. Some of the docs are .md (markdown) while the rest are the actual code files. I don't know how often they accept pull requests, much less for doc-only changes, but they have almost 150 PR's in queue.

And this is something I was unaware of until now, a "Contributor License Agreement"[1] is required for a pull-request to be accepted. Sheesh, that's kind of a PITA...

1. http://docs.angularjs.org/misc/contribute#CLA

It was a while ago when I last did it, but the team are perfectly happy to merge-in docs corrections and improvements. IIRC, the CLA is not necessary for docs either, only for actual code.

At the last London AngularJS meetup it was mentioned that the team have 'pull request parties' where they try to merge or close as many contributions as they can, but more of them just keep coming ... good problem to have I guess, but they are aware of it and trying to address it.

In my case it's because I don't understand it well enough to write doc. The people who _do_ understand it well have managed to do so despite the state of the documentation, so maybe they think the doc is sufficient?

It's one of those nasty problems, like the influence of money on politics, or gerrymandering, where the people best able to fix it are the ones least likely to think it's a problem.

A lot of us have invested a lot of time learning Angular, pains and all :) . I've contributed to the docs, as well as source. I've also reported issues, big and small.

The current docs have come a long way from their previous state - I recommend people try taking a look at them now. The developer guide & API docs have gotten huge improvements within the past month! I think the only things that are really left is to recommend some best practices with examples and more examples in the API section.

The barrier of having to contribute via GitHub is actually a fairly large one. Think about it; not even all developers understand git. The design challenge of creating a simple way to contribute/improve documentation (read: educational materials) is something we're working at Coursefork [1]. It's a tough one to solve, but we think we've cracked it.

[1]: http://coursefork.org

/shameless plug

> Google has the chance to build the new framework that will run the web in 2-3 years. Much like Rails a few years ago. Angular is an amazing framework. It seems like they just don't care.

People use to say that about ExtJS a few years ago , then BackboneJS, etc ... There will never be one framework to rule them all , like Rails never ruled server-side developpment, Rails influenced other frameworks. Likewise Angular will , and something better than Angular will come by.

> Angular needs someone versed in developer usability to take control of the public facing Angular stuff and give it a complete overhaul. Right now, it's the result of hundreds of people haphazardly making changes.

that's how most open-source projects work. Angular is not a Google library, Google already has closure[1] , which is neat and scales(ie great performance,unlike Angular), Gmail is built on top of it , but strangely nobody else but google is using it...

EDIT :

[1] https://developers.google.com/closure/library/

Maybe my understanding is wrong, but closure (and closurescript) are compiled languages. Angular is a UI framework, so comparing them is apples to oranges.

And I think the Angular community would be thrilled if it had even close to the kind of documentation that Rails has. You are correct, no one framework will rule them all, but there are examples of OS projects that have good docs (like jQuery and Rails) that can be used as comparisons when evaluating a framework.

I'm talking about the closure library, it's a javascript library written by google :

https://developers.google.com/closure/library/

All google Saas apps use this lib.

You may be thinking of Clojure and ClojureScript — with a J. It's confusing naming, but those are different, and are not Google products.

In this thread, we're talking about Google's Closure (with an S) Library. Google also makes a Closure (with an S) Compiler, but it's more of an optimizer — it "compiles" from JavaScript to optimized JavaScript.

further adding to the confusion, clojurescript targets closure compatible code

I would prefer to clear the confusion by calling Closure templates "soy templates", and differentiate it from the Closure compiler (for compiling javascript).

The pedant in me would like to emphasize that clojure-with-a-j predates the google product by over 2 years.

I am fairly sure I have seen tutorials on using the two together.

ClojureScript uses Closure.

This seems like such a huge win, I'm it's not more common with other compile to js languages.

It's not so common because:

- It requires a running JVM to compile it all down (not a bad thing).

- Can take upwards of a second to compile depending on code base size and compression setting (even if the JVM is warm).

- Kills all ability to debug. Looks like "a.call().call()" etc.

That said, ClojureScript has been fun to work with, but IMO, Google Closure as dependency thwarts a lot of people looking to try it out like they might try CoffeeScript or TypeScript.

http://cljsfiddle.net/ goes a long way towards having a tool people can just play with to try out ClojureScript without being twarted by setting up Clojure/JVM/Lein/Lein-cljsbuild/

i m certain you can pretty print the resulting compiled js. see http://googleclosure.blogspot.com.au/2010/10/pretty-print-ja...

and don't forget source maps

Maybe I'm a bit of a masochist, but it's not that hard to read the compiled output, especially when you have a decent mental model of what it should be. It doesn't look like idiomatic javascript, but the structure is pretty regular.

Here's an example for the kids at home.

compiled: https://github.com/gtrak/node-cljs-template/blob/master/src/...

from: https://github.com/gtrak/node-cljs-template/blob/master/src-...

It uses the closure compiler. Not the closure library.

We've been running a client side SaaS on the Closure library/tools/compiler for a couple years now. You are right that it is not widely used outside Google (and certainly not as popular as Angular) but it is well-tested and there are some people out there using it for production work.

I think Angular is just the latest in their web dev portofolio, driven by internal needs. They have Closure, which is basically their own jQuery + package/module/dependency loader & framework. Then there's Dart, which is kind of their version of CoffeeScript/TypeScript/etc. (and even looks strikingly like Angular at times[1]).

There are definitely overlapping concerns, but they've dogfooded Angular for both the YouTube TV[1] portal as well as their DoubleClick site, and so I don't think it's just for external purposes.

1. https://www.dartlang.org/polymer-dart/

> Then there's Dart, which is kind of their version of CoffeeScript/TypeScript/etc.

From my point of view, it's just the next logical step after GWT and Closure. The annotations are baked into the language's syntax, you get the usual JS-like development cycle (save -> F5), and Java/C#-like tooling.

TS is somewhat similar. CS, however, isn't. CS doesn't offer any tooling advantages over JS.

> looks strikingly like Angular at times

Heh. There is also a Dart version of Angular:

https://github.com/angular/angular.dart

I thought Gmail was a compiled to JavaScript from Java application?

Nope, you're thinking of GWT. Relatively few Google products actually use GWT; the bulk of them are on Closure. GMail's client (and Google+, and Docs, and Search) all use Javascript-compiled-to-Javascript for the client side.

I've always wondered why GWT isn't much more popular (at least, for google properties). I know of a half dozen apps written in GWT by google. The rest is probably in closure (or something else).

Perhaps they still haven't solved the SEO problem of GWT internally, and so only things that don't need SEO-features like control panels, dashboards (but ironically, the google groups forums too) are in GWT.

GWT is seen as extremely slow (especially compilation times) and not suited to heavy client-side applications.

I don't think the SEO nature of GWT is fundamentally different from Closure or Angular.

a lot of people who i've spoken to have the same impression of GWT (that it's slow, and not "webby"). I suspect it's because it has the same UI library model as java Swing, and that has the reputation of being slow (thru no fault of java to be honest - its usually the programmers who made it slow, when it could've been fast).

http://www.google.com/fonts <-- loads fast for me. In fact, i think GWT apps can do loading in such an optimized way that hand coding js will only beat it if the programmer is very very careful about it.

(ps, i have no affiliation with google, i just don't like mistunderstood tech to suffer…)

GWT on AppEngine (which it has great integration for) has a ten second startup time when not loaded, and on the free tier they unload it when not in use, so that's not the greatest.

I used GWT for a while and it would be great for enterprise and large teams. The static typing which I usually love/insist on though, does seem pretty cumbersome for something as simple as a web page. I've switched to scala play for the back end and lots of tiny angular 'apps' on the front, and it's so much faster to develop for.

you should try out closure. it has static typing and a really well developed and tested library alongside the fantasitc compiler.

Significant parts of the Ads management front ends are written in GWT, but Closure rules the consumer facing front ends.

gmail existed before GWT was created.

But i m pretty sure GWT was created as a result of the research/code written for closure (which, even tho it was opensourced after GWT, existed before GWT in some form or another).

The problem with Closure is that it really sucks for small projects. It was built for large products with hundreds of developers and millions of users; many of the library features (eg. static typing; dependency management; compilation; CSS renaming; namespacing & scoping; full component libraries) are absolutely invaluable for that use case, but don't get you much when you're just prototyping a few ideas. I don't think Google's webapps could run on any framework but Closure, but when I and many of my coworkers want to do a quick prototype, we reach for JQuery or Angular. Or even just native DOM APIs.

All big projects have to start out as small projects first, and so most small projects. If a small project uses a framework that's great for big projects, they're paying all the overhead for that up-front, which puts them at a disadvantage in the marketplace. I could see Closure being quite useful for rewrites, but once a dev is in charge of rewriting a project with dozens of devs and hundreds of thousands of users, he probably doesn't have time to blog about the latest JS framework.

We started our project from the get go in closure because this overhead can be automated. The benefits outweigh the pitfalls IMO, and a week spent on process will pay huge dividends down the line.

If you're really spending 90% on Google, and 10% writing code, then you're doing it wrong.

At least a good 30% of your time should involve reading code. In any framework.

That said, AngularJS' code is magic in places. The magic is contained within small modules, or at least as small as those can get for what they're supposed to do.

But documentation is only enough to get you started. In any framework.

(And in my experience, proprietary frameworks and APIs always involve lots of email back and forth.)

I was of course generalizing -- by "Googling", I meant everything from reading StackOverflow to browsing GitHub to looking at the docs.

That being said, I'm not quite sure where that 30% figure comes from. Whose code am I reading? Why am I reading it?

Angular isn't your run-of-the-mill framework. They've reimagined almost everything. That's fine (and for the most part, I like what they've done) -- but documentation is incredibly important.

AngularJS code. I regularly dive in whenever I run into an obstacle.

The 30% figure is a wild guess, and may sound a bit large, but I certainly spend a lot of time reading other people's code. Or even rereading my own code.

Docs can be improved, absolutely, but there's no framework where I didn't feel that way about documentation. I don't think I've worked with any framework for more than an hour without looking at its code.

> At least a good 30% of your time should involve reading code. In any framework.

Understand that not every developer has a good knowledge of these frameworks. Understanding the DOM, browser-specific JS stuff are not piece of cake. Hence documentation is super crucial to have.

This is like asking every developers to read Linux kernel video driver when their video driver crashed.

So you're learning a lot more than just AngularJS, then, and attributing the problems you run into along the way to AngularJS.

Maybe AngularJS is hard to grasp if you're not already familiar with the DOM, compared to other frameworks. I wouldn't know, to be honest.

Your video driver example is not a good comparison, in my opinion. You're comparing developers to users. If a developer triggers a bug in a video driver through some specific OpenGL calls, he will certainly try to develop an understanding.

(The bad part about video drivers is that the maintainers of proprietary ones are hard to reach. But Valve is doing it, I guess because they have contacts.)

You understand a lot of people using Linux are developers. That comparison is not so bad. Yesterday I was playing counter strike and an error popped. I did a quick search and I could have fix the file in place but instead I just use built-in feature to fix the error. As a developer, I rather have someone to deal with that problem if I had the choice.

Learning Angular.js internal is not interesting to most of us. Sorry. We are users too. We are developers but we don't want to develop angular.js because we don't have time and we don't have the experience dealing with DOM and browser. I know this sounds harsh but in an open source world developers are users too. Documentation is the the emergency call to developers. IRC is not always helpful and most of the time core developers are not available to talk. Imagine someone from India asking help while East Coast is sleeping.

Here: https://github.com/angular/angular.js/issues/3753

I don't even know where to start. This is quite browser specific.

You misunderstand. I don't expect a Linux user to understand video driver internals. But I do expect a developer using OpenGL to have some grasp of the situation once he runs into a problem.

I strongly urge you to learn and understand the tools you are using. It's what makes all the difference between a good developer and a great developer.

There's nothing wrong with the issue you reported. Nobody is asking you to send patches. (Though that would be nice.) But you've already added a small test case, so that's excellent.

There are always things you can do to get a better understanding. For example, take AngularJS out of the equation. Turns out, you can add options to a select element and everything's fine. Only once you set the select value, does Firefox flip the highlighted item.

Why?

I use Django on the server side, the documentation is superb (compared to Angular's). I hardly ever need to dig inside the code, unless I want to do something quite special.

I have a good idea of how the framework works, what pieces fit together where, but I never feel the need to go in and read the code for it.

And what about proprietary software? I am sure there are plenty of frameworks where you can't get to look at the code.

Between frameworks like Ruby on Rails, Node.js, AngularJS and smaller libraries like Backbone.js, jQuery, and jQuery UI, I've relied more on code for all of them. Documentation has only ever helped me to get started, and as a quick reference. But do anything significant, and thorough understanding is simply a must; something I can only find in code.

I also do a good amount of work with the Twitter and Facebook APIs, and in my spare time work on a fairly complex Cocoa project. Working with all of these is a whole lot of poking at interfaces until they do what I want. These all have tons of documentation, but they'll never be pleasant for me to work with.

I've actually found AngularUI's docs to be pretty okay.

I don't think Google created Angular, but rather a Google employee. I'd imagine if Google fully backed Angular, the syntax/design would've been much cleaner. Angular with a fresh boot would be something I'd hope for, they just keep adding things on top of it to keep BC as much as possible which is why it feels so dirty at times. I too get (extremely) frustrated with Angular at times for all the points mentioned by OP. Honestly sometimes I don't even know why I bother with it, I feel it being counter-productive if I actually think about it. It just seemed cool concept at the time but over the long run, I feel I am just digging my own grave. Great post for venting about the frustrations, I been needing to vent myself too.

Angular used to be its own startup. The founders were acquhired by Google.

Where'd you get the wrong idea that it was a Startup?

AngualrJS was a side project of Misko, who was working at Google on the DoubleClick team, until he bet he could rewrite DoubleClick in 1 or 2 (can't remember) weeks using his framework and cut down on the LOC/code complexity. He eventually did and they decided to go full time on the framework. They discussed this at the start of their Google IO presetation.

[0] which leads to [1]

IIRC, They had a plan to provide a paid or freemium server-side counterpart. edit: freemium, see the first revision of getangular.com[2], there's a pricing tab which disappeared later on.

update 2: they were not acquired, they abandoned the startup because it did not get enough traction. The framework lived on, though.

Development history

AngularJS was originally developed in 2009 by Miško Hevery and Adam Abrons as the software behind an online JSON storage service, that would have been priced by the megabyte, for easy-to-make applications for the enterprise. This venture was located at the web domain "GetAngular.com", and had a few subscribers, before the two decided to abandon the business idea and release Angular as an open-source library.

Abrons left the project, but Hevery, who works at Google, continues to develop and maintain the library with fellow Google employees Igor Minár and Vojta Jína.[3]

[0] http://web.archive.org/web/20100601201616/http://www.angular...

[1] http://web.archive.org/web/20100413141437/http://getangular....

[2] http://web.archive.org/web/20091002201638/http://www.getangu...

[3] https://en.wikipedia.org/wiki/AngularJS#Development_history

i don't dispute this, but it pretty much flies in the face of everything the team has publicly communicated so far.

Any thoughts on why the whitewash? Maybe to get better traction as being a 100% google skunkwork?

Easier, simpler story to tell than the long version, of which the details don't really matter?

I stand corrected, my apologies. I simply assumed that it was Misko's side project (by assuming, I mean made an ass of myself). I'm going to pay more attention next time they talk about its history to see if they actively attempt to not bring that part of its history up. Agree with novaleaf, it's super weird they never mentioned it.

I can totally relate to "they just keep adding things on top of it to keep BC as much as possible which is why it feels so dirty at times. I too get (extremely) frustrated with Angular at times "

Personally, I skipped the docs and went straight to the API guide. Reading that had me only Googling for edge cases, such as scope changes within ng-repeat.

AngularUI is indeed very much 'off on their own doing what they want', they are not a part of the core team AFAIK. Even inside the AngularUI team, quality, convention and style can be dramatically different across different modules ( cough ng-grid ).

Sounds like something that could be crowd-funded - pay some contributor's salary for a while to write the docs :).

Google has the chance to build the new framework that will run the web in 2-3 years.

Not to be a cynic but I'd rather not have more Google-controlled software take over yet another part of the internet.

The internet managed just fine without Google before, and I'm sure it will manage fine without Google in the future.

Right now Google dominates almost everything, so whenever I'm given a choice between something made/controlled by Google and anything else, I will go almost instinctively go with the "anything else"-option just to provide some counter-balance.

Google is scary as shit these days and can do pretty much whatever they want without consequences, and I just don't want to be part of making that worse.

The docs are fine. There can always be improvements, but it isn't orders of magnitude worse than other frameworks as people persistently claim.

The doc for "mock" is a funny example of how poor the docs are in places http://docs.angularjs.org/api/angular.mock

An effort is being made right now to rewrite the concepts docs in better language - and moving out from there.

I agree with most of the things mentioned in the article, but here are a couple of nits, just in case you have that exact problem and look for the fix:

$timeout having no $cancelTimeout: that's just called $timeout.cancel(), taking the promise you got out of the initial $timeout call.

$.when is called $q in AngularJS, support for promises actually runs deep in the framework.

Regarding the difficulty of instantiating controllers, and controlling who publishes what on the $scope when: I think there should be a style rule that you never, ever have some piece of JavaScript depend on the fact that some other piece of JS adds a variable to its parent scope. Yes, that's global state, or dynamic scoping, and should never be used. Just create a service if you need two directives to communicate. This gets more obvious and easier with 1.2 and the controller-as style.

Bi-directional data binding should never get you into a loop if you take care to only use the APIs in ngModelController. If you managed to trigger a loop, you're probably using the wrong API - loops are something that can happen in bi-directional data binding, but it's not a given.

This is not to say the author is wrong, as said above, I agree with most of his points.

Yeah, he had a few minor incorrect details - the $q one was a big omission, it sounds like he never explored using $q.all, much less $q at all.

I think Angular's complexity can be daunting without someone who can help set you back on the right path when you're stumped. We (the regular denizens on IRC) do a pretty good job in #angularjs on Freenode helping people out when we can, but it's obviously whenever people can spare the time to answer questions. I am constantly helping people at work grasp how to think the Angular way, and it has resulted in my team being incredibly productive due to Angular's excellent upsides.

Regardless though, I think it's good that this article was written, even if a little prematurely. People should know both the upsides and downsides.

Hi author here. Thanks for the feedback :)

re: instantiating controllers - services definitely help, but you still have to design and expose APIs to manage the lifecycle of variables from the controllers, and often times (at least for me), there are a lot of cross-concerns and it becomes impractical to have services to deal with each permutation of concern groups (this is especially a problem in more exploratory projects). I should note that in the cases where maintainability suffers the most, I have upwards of 5 core model entities and a dozen other auxiliary ones being manipulated in a single page.

Also, when things need to persist across route changes, then you're pretty much stuck to polluting $rootScope (or worse, $cookie)

re: "Bi-directional data binding should never get you into a loop if you take care to only use the APIs in ngModelController"

Yes, they shouldn't, but under some unexplainable circumstances they do, even when I'm explicitly avoiding all the other undocumented traps (e.g. isolated scope interop, etc). One very big weakness in Angular is internal integration testing. Given enough moving parts, even simple things that should just work start breaking in very strange ways (looking at you, ng-if).

So why does Backbone.JS suck then? :)

Shameless subreddit promotion: I (and the rest of the members) are trying to submit every single worthwhile AngularJS article to http://www.reddit.com/r/angularjs so that it becomes a solid place to keep up with AngularJS tutorials and guides.

So far we've almost doubled the subscriber-base in about 3 months so things are finally starting to snowball a bit in terms of participation.

Why Reddit?

I didn't start that subreddit actually, just became a mod a few months ago. Reddit is easy for these types of things because so many coders are already using it to browse other subreddits. I'd prefer it be its own site entirely but this is working well for now so no need to mess with a good thing.

> I consider myself to be a reasonably good js developer, but the internals of AngularJS are overwhelmingly non-approachable.

Same here. I'm just getting up to speed with Angular. I spent the past weekend developing a web-app to manage our internal test-process. I like it a lot, I managed to create an incredibly complex and interactive web-app in two days.

Well, I say I like it a lot, I like the idea a lot: data driven mark-up, separation of concerns, etc.

However when it goes wrong it's incredibly difficult to step through the Angular code to work out what on earth is the cause of the issue.

It took me several hours of poking around trying to get this tree-view directive to work:

http://ngmodules.org/modules/angular.treeview

First to try and work out why the directive wasn't being initialised, then why the parameters were coming through with different names of the properties compared to what the original source expected (ngTreeModel rather than treeModel for example). Then, why on the inner elements of the tree the properties coming through were named as expected!

So exasperated I head over to the documentation for directives, and, yeah, horrible... incredibly dry and terse.

I never quite got to the bottom of the issue, and have deferred working it out until I know Angular a bit more (var treeId = attrs.ngTreeId || attrs.treeId).

But I can't deny that this thing is incredibly powerful, so I think it's worth persevering with. But yeah, some better docs and up-to-date examples would be very, very welcome.

EDIT:

I remember reading this a few months back. Now I get it...

http://www.bennadel.com/blog/2439-My-Experience-With-Angular...

Angular, when it feels right, makes me incredibly productive, but I feel like I spend 90% of my time banging my head against a brick wall.

One of the single biggest usability features of anything is giving things appropriate names. The "other half" of Karlton's law is well in effect here. Angular fails miserably at this task. And that makes reading documentation, as well as maintaining enough context in my head to be productive nearly impossible.

From a documentation standpoint, the documentation focuses on "this is how this function works internally" rather than "this is how you use it to produce results".

I want to like Angular. So much of it feels right, and technically it seems excellent. It really is a usability nightmare, though.

I agree with you that it's frustrating at time. Especially when angular does magic stuff that you're just supposed to know. Like fuck with your existing links and stop existing forms from working.

And sometimes, real easy things are so complicated.. For instance, try to make a form post on the current page. (Hint: If you don't have action="", then the form doesn't post. But, by default, no action usually means submit to current page.) (Hint2: Probably more a hack than a real solution, but I've just used an onclient event on the submit button to manually post the form..)

http://docs.angularjs.org/api/ng.directive:form explains it pretty well.

Sure, if you read all the doc and stumble on this page.. but for a newcomer it's damn surprising to see existing code not working. It's like adding jquery and having random links disappearing.

I feel like I spend 90% of my time banging my head against a brick wall.

Why do people want to work with a technology like that?

Personally I feel that the worst part of programming is when you're stuck trying to decipher the inner workings of an intermediate layer. It's so frustrating and futile, and I'm not learning anything generally useful because mastering arcane workarounds for technology layer X doesn't translate to anything else.

I'll much rather work with technology that doesn't make me feel magically productive 10% of the time, but does make me actually productive 99% of the time. There are plenty of those around.

I agree. What I'm trying to determine is whether or not it's a rabbit hole going down. Am I using a very powerful tool that's user interface is fine, but takes a little bit of time to learn. Or am I using a very powerful tool that has a user interface that's just bad. I'm honestly not sure - I haven't spent enough time with it to tell.

And yes. A programming language or framework is/has a user interface.

Why do people want to work with a technology like that?

I do because studying advanced frameworks and working within them is the main way that I learn new patterns.

I've been doing (mostly backend) webwork for a living for about half a decade now; the last ~6 months I have been building an app that is using angular.

I agree the documentation sucks; but beyond that I actually don't have any complaints. I don't have anything to compare it to; but I have written some JS over the years and what angular is doing is blowing my mind.

Because it blows my mind I find it hard to bitch or find fault. I did have to spend several hours stepping through angular core code to figure out WTF was going on with $scope.$watch(); but again, I can't really say that $watch itself sucks; just that I had to read the code to actually understand how to use it.

If I had to pick something other than documentation to point at, I would say that silent shadowing of non-object primitives when "new" scopes are creates for things like ng-repeat and ng-if

This is a good set of arguments explaining some challenging corners of AngularJS.

It is true that when you start getting into the realm of edge cases, substantial knowledge of the framework's internals is required to put together a solution that is consistent with the 'zen of Angular'.

The author argues that some of the challenges introduced by Angular's $apply lifecycle and its approach to two-way bindings make it a challenge to use in certain circumstances. I would rephrase that and say that Angular's state-tracking and two-way binding solution is a very elegant hack to a very complex problem, considering limitations imposed by javascript, css and html. Angular proposes a set of integrated solutions that allow developers to avoid a substantial amount of boilerplate (and complex boilerplate, at that) for synchronizing state and the view. As with every other framework, it is not appropriate for every problem.

That being said, I continue to use and love Angular in a complex app with quite a few moving parts. I migrated from Backbone.js about a year ago and never looked back.

/x-post from Reddit: http://www.reddit.com/r/javascript/comments/1pdzbz/things_th...

I found Angular to be overly complex and couldn't imagine training a team to learn to use it in reasonable time. That's the scariest part of adopting Angular for me. How would other coworkers adapt to the API and how long would it take for them to use it?

The documentation was o.k at best, but I find that isn't the core issue. If you take a look at http://docs.angularjs.org/guide/concepts, it takes a very long time to completely understand what's happening under the covers.

I'm definitely looking for alternatives.

I disagree. I very like how the learning curve of angular follows my simple to complex application features. What I mean is that it's very easy to get started and hack you way through something that work, even if it's not 100% angular best practices. I.e. putting jquery code in your controller. As you become better and better, you start to have a better understanding of how angular works and your code improves similarly. I think this is an amazing quality for a framework. It reminds me how fun it was with jquery to get started even if the code was terrible, and then improve from it as you learn.

For a newcomer to an angular project, they can simply read the html and have a pretty damn good idea of what's happening. You don't have to start writing directives and play with transclusion right away.

Check out Facebook/Instagram's React: http://facebook.github.io/react/

Simpler, and fast. I haven't messed with Angular enough to give an honest comparison, but I'm a fan of React's general design - it maintains its own model of the DOM, and user interactions change that model, then it diffs the new DOM back to the browser DOM.

Fwiw this idea seems to slowly be catching on. There are at least two other frameworks that use a similar model - theGuardian.co.uk recently open-sourced their frontend JS framework Ractive, and the Lift web framework impllements a similar model on the server side (been around since 2007, just now the idea seems to be making its way to the frontend).

In my experience I've been teaching to friends over lunch. I think as an analogy it's like jQuery - it's easy to learn the basics and actually do useful start within a short time, but I you want to go for the deep end there is a really deep end.

The Angular docs are a ghetto. They really need to get rid of the Disqus comments section. Also, I don't think it really helps that their docs are an Angular application. I would really prefer a static html manual and an offline version in pdf or info format.

If you think angular docs are bad , you should try ember. Ember is so frustrating. All answers on SO are out of date or wrong.

To be fair it's the same with angular.

Neither good SO answers nor docs emerge out of thin air. If you find the right way to do something, document it, write it down, submit a PR.

Ember creators cleary did not know where they were heading when they began writing it.

AngularJS was influenced by Flex and Spry( the creator worked at Adobe ) from the start, and still is.

Ember was heavily influenced by Sproutcore

Ember WAS Sproutcore, Sproutcore 2.0 is what became Ember.

Worth noting: Sproutcore was used to build iCloud, apparently.

that's what I thought, so clearly Ember wasn't written from Scratch

It used to be like this, but throughout this year in preparation for the 1.0 release the devs really stepped it up. The official guides are good nowadays.

I've found quite the opposite. Ember docs are very clear, constantly being refined and tweaked, and the core devs are actually willing to take input to improve upon them.

The ember docs have improved immensely over the past few months - they're currently significantly better than the angular docs.

Been using (or, trying to use) AngularJS for the past 2 months.

The way to get around the bad documentation for me are sites like http://egghead.io/ and http://thinkster.io/ (and of course, tons of SO-ing).

I tried these, and they explain all the components nicely, but don't explain how to put everything together to get a mid to large scale app put together.

Maybe I just struggle as I am new to front end development, and to stuck in my server side mindset.

Egghead is great and all, but it's really useless if I want some important feature explained in-depth. (What do I need to define for it, what actions does it have, what is it use for, what is the best structure for it, etc etc)

JQuery.when is similar to $q.all http://docs.angularjs.org/api/ng.$q

So, a lot of people complain about AngularJS's documentation, not just this article or the comments, but everywhere.

Does nobody see the bright 'Improve this doc' button at the top right or something? It's an open source project - instead of complain, contribute! The link immediately opens a github pull request for your convenience and you can edit it in github's own editor.

Yeah, you could shift the blame to Google, but afaik, it's not one of their supported products, but a 10% time product - meaning that the creators / maintainers themselves can't work full-time on it either, and rely on the open source community to help them out.

Go forth and fork.

Improving docs is a bit of a chicken and egg problem: someone who's having a hard time with the docs is not going to be able to help improve it.

Surprised the knock is bad documentation (The site is awful), but I have heard that Angular has a lot better documentation then Ember currently does

Ember is still changing a lot, and some of the later changes are cleared inspired by Angular.

Ember-data looks much better than anything in Angular. Ember has a bit too much "convention over configuration" to my taste but the project is evolving well; I would not say it is production-ready but is getting close, so keep it under the radar.

My biggest pet peeve is how it suppresses errors in inline expressions.

Fucking hell. I do like AngularJS, but everything to do with expressions pisses me off. Fairly incoherent documentation, combined with lack of errors or any sort of meaningful way to debug them.

No doubt, care to share how you feel about $scope inheritance?

Can't google just hire an intern to update the documentation? C'mon guys, it would likely be the very cheapest and most effective thing they could do at this point.

Angular has 'from Google' written on it, but it's not a Google-created project. They make no money from it, and Closure's way more popular inside Google.

They'd hire an intern to fix Closure bugs.

AngularJS explicitly [1] states that its suited best for standard CRUD apps. If you need to do something which requires touching the DOM or some low level manipulation, better stay off it. We decided against it while building our GUI Editor ( adpushup.com), and decided on Backbone (w/ Backbone relational). Backbone is a library (as opposed to being a framework) and plays really nice with jQuery and vanilla JS.

However, there'll be projects/components for which AngularJS (or EmberJS) would be better suited, and we'll surely love to give it a try.

[1] : http://docs.angularjs.org/guide/overview

I absolutely love angular. Documentation is a definite given. I was having a problem with resolving an ng-class on <body> with $rootscope and I thought, "I'll go look at $rootScope's documentation!"

http://docs.angularjs.org/api/ng.$rootScope

Psyche. Good god.

Please do not use a framework that you do not understand. It is not good for the sustainability of your application. It is better to read/maintain a verbose application than dealing with some obscure magic.

I tried to learn AngularJs but I can't understand it so I gave up and used a simpler and more limited JS library (ractivejs).

There's also a lot of missing fit and finish.

For example:

   watch( watchExpression, listener, [ objectEquality ] )

   watchCollection( obj, listener )

Yet in watchCollection, like in watch, 'obj' can be an expression that is evaluated.

When I first started using Angular I actually bought a video course on it from Pluralsight. So when I started my first Angular project I hit the ground running.

There are also a lot of free videos on Youtube, that sometimes explain things more clearly than the docs.

A framework guides you into a determined way of doing things. It is a known tradeoff: 90% of what you need to do is simpler, 10% may be a little harder. I have now built two medium-large web apps over the last months with Angular and while, naturally, it's not without problems, I have found that most of my difficulties were due to me doing things in a non-Angular way.

I also find it is going in a very good direction with the recent changes in 1.2.0. They listened to a lot of feedback from the community.

Where are the Angular devs? Are they not paying attention? I would expect at least ONE contributor to see this article and take in the feedback, offer advice, make corrections.

> The page for directives is another (in)famous part of the docs that, despite relating to one of the most important aspects of the framework, is often derided as being overly dry

While that used to be true, the directives page recently got updated to provide a much better and simple guide to directives along with plently of code samples - http://docs.angularjs.org/guide/directive

There is still some work to do. Read the paragraph about transclude : true? $transclude is one of the best features of advanced directives, and the paragraph is still the old one which leaves you with a "... what?" even after you read it 5 times. An example is very much in roder here, but how long should the article be? Before, this section was actually in the guide, and the doc for $compile was neat and clear. Now it's actually messier than before.

I've been turned off by the Angular docs (feels like how I found API refs intimidating when I started coding) - can anyone recommend an alternative or book?

I've read "Mastering Web Application Development with AngularJS" and I thought it was pretty good at explaining difficult concepts in AngularJS.

In my opinion, despite some of the worst parts of Angular, we can use Angular as an integration with existing front-end web framework. We can make AngularJS work smoothly with the site running normal Ajax request, single page technique... (as I made Angular working with OpenERP few days ago).

By this way, we can save a lot of time dealing with DOM and re-use all existing technique too.

Got also into Angular for some while and my verdict: if this wasn't made by Google it wouldn't haven gotten off the ground. Its concept has too many quirks and isn't thought through. Tried recently React and this feels much more sane, you have to relearn stuff but it's way less than Angular and performance is better.

Worst for me: hooking up Angular with a stateless REST API without using a middle layer application for authentication.

Every framework has pros and cons. I also suggest you have a look at EmberJS. All those features you are missing in Angular are there in EmberJS like promises using Ember's RSVP etc...And then EmberJS may be having its own cons...Testability is one of them..

Those people here looking for a tiny, sane MVC framework with live bindings should try CanMVC. After doing a bunch of frameworks (JavascriptMVC, DoneMVC) I think that company produced a simple, well documented framework better than Backbone.

As you dive deeper into Angular it becomes clear a lot of it is unpolished. For example $resource seems very half baked. It has lots of quirks e.g. trailing slashes and its promises support seems to be a bolt-on.

I prefer rivets.js. I just need a little library for object binding, I don't need weird java-like concepts.

wow, nice find

Pah! Let's write all our code in hex. We can't have the government getting involved in anything!

Ron Swanson approves this message.

Reply on news.ycombinator.com