One of the things I enjoy about teaching seminars is that it gives me a chance to interact personally with people who are learning the subject. This experience provides a perspective that I think would be helpful for some of the Rails core team, which made one decision in Rails 2.0 that has caused a lot of unnecessary pain for people learning to use Rails.

In Rails 1.2, the “scaffold” generator takes the name of an existing model and generates a controller and views for the basic CRUD (create, read, update, destroy) operations. Almost every introductory book uses it, and most of the online tutorials use it.

Rails 1.2 also introduced a new generator, scaffold_resource, which produces a RESTful controller and corresponding views. It is a conceptual replacement for the original scaffold generator. But it works quite differently. It doesn’t take an existing model as a parameter; instead, it takes the name of a model to be created, and a list of attribute_name:attribute_type pairs, much like the model generator.

So far so good. Everyone keeping up with the leading-edge ideas started using scaffold_resource instead of scaffold.

But then, with Rails 2.0, the old scaffold generator was relegated to the dustbin, and scaffold_resource was renamed simply scaffold. The result: nearly every book and online tutorial now fails, without any error message. Countless people trying to learn to use Rails are left needlessly frustrated and confused.

I understand the thinking that led to this: the core team wants to push RESTful design, and they wanted scaffold_resource to become the primary scaffolding tool. That’s fine. And for experienced developers the change in the scaffold command is not a problem.

But taking a feature that is almost universally used in introductory tutorials, and creating a new feature that works in a fundamentally different way but has the exact same name, is just a bad idea. If the core team was determined to dump the old scaffold, they should have replaced the generator output with a message that you should use scaffold_resource instead, and explain that it works differently.

Of course this is all water under the bridge, but I hope the core team thinks about the unnecessary pain this caused for many people trying to learn the platform the next time they consider redefining what a feature does. Please don’t reuse existing names to make them do different things in silent and confusing ways. And give some thought to the difficulties that may be creating for people attempting to learn the platform from the existing tutorials, and how you might mitigate those difficulties.