13 ms·

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, i

by devmach 15y ago

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.

knowtheory 15y ago
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/ http://backbonejs.org/ ), the annotated source itself (http://backbonejs.org/docs/backbone.html 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-blog-posts-and-example-sites https://github.com/documentcloud/backbone/wiki/Tutorials%2C-...
jashkenas 15y ago
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 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/public/javascripts https://github.com/documentcloud/documentcloud/tree/master/p...
- ashchristopher 15y ago
  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.
- sophacles 15y ago
  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.
- peregrine 15y ago
  Part of the problem is that everything is in paragraph form. So for instance the http://documentcloud.github.com/backbone/#Model-fetch 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 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.
  - jashkenas 15y ago
    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.
jguimont 15y ago
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.
devmach 15y ago
* 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.
brown9-2 15y ago
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.
- devmach 15y ago
  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 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.

by devmach 15y ago

knowtheory 15y ago

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/ http://backbonejs.org/ ), the annotated source itself (http://backbonejs.org/docs/backbone.html 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-blog-posts-and-example-sites https://github.com/documentcloud/backbone/wiki/Tutorials%2C-...

jashkenas 15y ago

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 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/public/javascripts https://github.com/documentcloud/documentcloud/tree/master/p...

ashchristopher 15y ago
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.
sophacles 15y ago
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.
peregrine 15y ago
Part of the problem is that everything is in paragraph form. So for instance the http://documentcloud.github.com/backbone/#Model-fetch 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 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.
- jashkenas 15y ago
  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.

jguimont 15y ago

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.

devmach 15y ago

* 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.

brown9-2 15y ago

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.

devmach 15y ago
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 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.