Hacker News Reader

Comment by devmach | Hacker News Reader

What bugs me about backbone.js :

* Lack of documentation. Every time, when i want to do something more than "todo app", i have to read the source code. Well, it's OK and a programmer has to read the source code to understand whats going on under the hood, but a little bit more good documentation can be really helpful.

* Examples are so simple. In a read world app it's more complicated. I have model ( persons ) and this model has collections ( contact datas, invoices etc. ) to find a way to handle all the mess i spend a weekend and read useless tutorials. In the end i gave up, read source code and my builded app on events. A better example could save my time and if there was a "best practices" guide, i could be sure that i'm on the right track.

View on HN

There are a lot of not-so-great blog posts and tutorials out there for Backbone, so I'm not entirely surprised to hear that you found them "useless".

It would be great to have a more step-by-step in-depth tutorial available on Backbonejs.org, and if I don't get a chance to built one out soon, I'd be glad to merge a branch that adds one.

Tutorials aside, is there something more in the way of API documentation you'd like to see, that you aren't finding on Backbonejs.org?

Finally, there is a long list of real-world apps available, many of which have viewable source code that you can examine and learn from:

http://backbonejs.org/#examples

... and DocumentCloud.org, the original application from which Backbone was extracted, has all of its JavaScript available on GitHub:

https://github.com/documentcloud/documentcloud/tree/master/p...

I've always thought a bit more explanation up-front about the philosophy, the way high level components/concepts interact, and the use cases would really help with backbone. The API is decently documented, but the context is not so well documented, and sometimes that is more important than the functions themselves (I can read code, but I don't want puzzle out which things that are technically allowed are bad/good practice within the lib's architecture).

edit/note: its been about 6-8 months since I was looking at backbone hard, so this may have improved.

I've enjoyed reading the Backbone docs and found them useful reference. Actually, I quite enjoy reading all of your project docs, @jashkenas!

But I wish the Backbone docs would talk about how to structure larger applications. Yes, I agree with the philosophy of "There's More Than One Way To Do It" but I don't think that's a good reason for the fact that there is no recommended best practice for how to modularize and organize code for a Backbone app that's larger than the trivial to-do example. Some discussion of architecture for larger apps, along with some example code, would be great.

At present it's an annoying contrast to see the small to-do example and the screenshots of elaborate examples that have many models, collections, routes, etc. Would be great if the docs could do a better job bridging the two.

Part of the problem is that everything is in paragraph form. So for instance the

http://documentcloud.github.com/backbone/#Model-fetch

explains in a paragraph that it updates the object and fires a 'change' event. Right below in

http://documentcloud.github.com/backbone/#Model-save

the text explains how the backbone.sync handles the save function. What's sets me back is that the backbone.sync strings "change" and "update" are both quoted and highlighted just like an "event". It is not apparent from the method call if an event is ever fired. Upon careful inspection you notice it also calls set if the values are passed or values are returned differently. The set method triggers a change event.

Eventually these things become second nature and you just know them. The tricky part is finding a good place to start from. Maybe a list of good practices, maybe a good up to date tutorial showing a simple app that uses models, collections, views, routes, and a real backbone.sync.

Ah, sorry. In that particular example, all of the highlighted strings: "change", "create", "update", are all JavaScript strings.

We should fix the Model#save paragraph to make it clearer that the strings are the potential values of the "method" parameter.

No problem, you asked for specific examples, and I figured since I'm writing my first large production backbone.js code I should chime in on my experiences.

Thanks for all the great work! I use and love BB, CS and _ everyday.

I think part of the problem is also that Backbone made some backwards incompatible changes as the framework developed. I found that a lot of the backbone tutorials were out of date - the &Yet blog had a bunch of good tutorials but were quickly out of date, and the posts were never revisited.

* Majority of the tutorials on the net are just useless. One can't uunderstand how the backbone internals works. We need more advanced tutorials than "Hello World with Backbone" and "Introduction to Backbone"

* Some important gotchas with backbone isn't documented ( or somehow i missed ), one example :

from document :

...

remove view.remove() Convenience function for removing the view from the DOM. Equivalent to calling $(view.el).remove();

...

in views, $(this.el).remove(); removes event bindings and if you call render() of this view again you should call also .delegateEvents(); somewhere in your code.

Just curious - if the documentation and tutorials were so lacking, what made you choose Backbone in the first place?

I ask as I'm looking for a new JS library for a project to build the client-side interaction, and I have no idea what is different than backbone from the rest, just that a lot of folks here are interested in using it.

There was two alternative for me : backbone and knockout. They are both good frameworks ( and serves different goals ).

* With backbone's models and collections, i can organize my application structure better. It's not easy but result is a clean code.

* Backbone's Router is no-brainer.

* Syc allow me to use RESTful JSON requests. Even i'm not using it, it's good to have such an option.

* Data-binding is a plain pain. You have to write your own code but there is always a library that you can use (eg. https://github.com/derickbailey/backbone.modelbinding ).

* I can always read the source code and thanks the comments i can understand most of it. My complain about good and advanced tutorials not because of the laziness, it was because saving time.

The code base for Backbone is small and hugely documented. Take 1 hour, read the code, feel good, learn techniques, let it sink in for a while and use it.

Seriously this is better than any tutorial you can find out there.

Is "lack of documentation" what you really mean?

Do you mean something more like, needs more howtos and sample apps?

'Cause backbone's got some pretty extensive documentation both in terms of the API (http://backbonejs.org/ ), the annotated source itself (http://backbonejs.org/docs/backbone.html ) as well as a big pile of references as well as tutorials here: https://github.com/documentcloud/backbone/wiki/Tutorials%2C-...

Reply on news.ycombinator.com