Monday, November 20, 2006

Ruby Nooby Review of Up and Running

Ruby on Rails: Up and Running, by Bruce Tate and Curt Hibbs
* Paperback: 167 pages
* Publisher: O'Reilly Media (August 1, 2006)
* ISBN: 0596101325
* Dimensions: 9.4 x 6.8 x 0.5 inches

This is a Qwik-N-Dirty little book that I like a lot. To say that it's quick and dirty is partly praise and partly a lament. There is a lot to like about this book and some not to. So what else is new in your life, then?

The book is about Ruby on Rails, the relatively new web development environment that has arisen from the blending of what is in internet years an old language (Ruby) and a new framework built on Ruby (Rails). Ruby is 11 years old, and now at version 1.8.5, and Rails is two and a half years old, now at version 1.1.6.

Ruby is the creation of Yukihiro "Matz" Matsumoto, who during a period of unemployment set out to create a programming language for programmers: "...we need to focus on humans, on how humans care about doing programming or operating the application of the machines. We are the masters. They are the slaves".[1]

Rails arose from David Heinemeier Hansson's work on Basecamp, a project-management tool which he contributed to at 37signals. He realized that the work he had put into this project could be extracted into a model-view-controller [3] framework that could be applied to other projects. And he wanted to put fun back into programming.

This book starts off well, with an overview of some of the guiding technical and philosophical aspects of Rails: metaprogramming, Active Record, convention over configuration, scaffolding, built-in testing, and the three standard environments for development, testing, and production. Then we explore the standard directory structure of a Rails application, views and controllers.

As the book unfolds we get more details on:
  • Active Record (the model part of MVC; an intermediary level between the application and its database)
  • Scaffolding (the controller part of MVC; automatically-built code linking application parts together)
  • Views (the view part of MVC; how pages render via various templates, helpers, and pieces of content)
  • Ajax (Asynchronous Javascript with XML; and how some of it is built into Rails) [4]
  • Testing (unit, functional, and integration)
There are also references to third party IDEs [5] and third party tools for testing. The final section of the book is a 31-page reference on tools, servers, and various aspects of Rails.

I came to this book after first working through "Agile Web Development with Rails", by Dave Thomas and David Heinemeier Hansson, et al. It was good.

My main problem is that after spending a good bit of time with "Agile" and rebuilding my personal web site, I did other things for about four months, and got really dumb again. I do that. It runs in the family. So I was hoping that "Up and Running" would be a good refresher and also give me another angle on the subject.

It has, sorta. Again, some things to like and some, well, maybe elsewise.

Schema Migrations

I do like the style of the book, and it clarified for me several areas where I thought that "Agile" was a little vague on. One thing I especially liked was the section on schema migrations. This isn't mentioned in "Agile", and maybe it's a new feature of Rails 1.1+. I started with Rails before version 1.0 came out, and "Agile" was also written in that environment, so that book obviously couldn't reference anything developed since it was written.

Rather than having to write DBMS-specific [6] SQL script files to drop tables and databases and then recreate and reconfigure them, migrations allow you to write Ruby code within the Rails environment, and then write add-ons incrementally. And thusly rejigger the database.

In other words, you create a database, and then you code the database schema, and Rails will create and manipulate the tables for you. An "up" routine will add features, and a "down" routine will remove them. This is very handy, and consistent with the rest of the environment: you get to write object-oriented code in Ruby, and don't have to switch to SQL and fumble with the syntax filter in your head while you're doing that.

Rails Console

This part comes just after the schema migrations section. "Agile" touches on this aspect of the environment, but much more briefly, and sticks more to basic, generic Ruby code than "Up and Running". The former book is 558 pages and the latter is 167, so the longer and more frequent examples in "Up and Running" form a relatively larger part of this smaller book. And they apply directly to the sample application that gets developed throughout the course of the book.

The first example brings up the console, a command-line, text-based application, and shows the reader how to access the newly-created database and even how to add new objects to it. Later on, you get to see validation at work. I know that testing is built into Rails, but a tool like this can be really valuable when you're starting to write code, and long before you have something to run through more formal tests harnesses, so seeing the Rails console in action was valuable.

Dynamic Scaffolding

"A Rails scaffold is an autogenerated framework for manipulating a model." [7] That's about what I learned from "Agile". That and learning how to create one. That was good, but only the half of it.

"Up and Running" describes a second kind of scaffolding. Not a command run once to autocreate directories and files which then can be further configured and tweaked, but a tag dropped into a controller. It adds capabilities through library calls inside one of the controllers you already have, enabling a quick evaluation of the developing application.

"The scaffold tag is dynamic, allowing you the freedom to build on the database schema; the user interface automatically changes to keep up." [8] They say, and "you can use Rails scaffolding to provide a simple user interface while you're working on your database schema. Your users can then verify that you're maintaining all of the data you need." [9]

Adding "scaffold :photos" to the PhotosController class allows the application to access the photos datbase table and enables you to add new photos to the database, list all the photos, edit them, and display them individually.

With one line of code. Amazing. Now I know this too. And it does work.

The Bad and the Ugly

OK, all of that plus lots of typos. There is a list of errata published at O'Reilly, but it is a short list of the actual typos appearing in the text. There's really no excuse for this. It's all too common in technical books, and guess what? Typos REALLY MATTER in technical books. When will they learn, these people? When, I ask you?

Part B, The Code Samples.

Ach, code samples. Things I do not like. Things which can however be lifesavers. When all else fails, drop in the canned code and keep working. Or refer to it later, to see how the pros format their code, or see it later to see how a particular thingy is built, a thingy you want but just don't quite know how to write.

And "Up and Running" comes with certified code samples, for chapters 1, 4, and 7, but not for the code through the end of chapter 7, the last in the book. Just for the START of chapter 7, before the final modifications. Too easy for smart people? Don't know, but we could use the final, finished code. We dopes, out here.

If you want to work along with the text and create the photographic slideshow application as I did, you'll probably need the supplied code. You can download it as zip files from the O'Reilly site. The code listings in the book are sometimes long, and not 1000% clear. The format for these could be a lot better.

It's not always evident when you're typing in a page and a half of code whether you're adding to something or replacing the whole shebang. This is a perennial problem with coding books. Maybe they could post it all online somewhere, with "before" and "after" sections circled in bright colors for us dummies. With lots of arrows and big print for us to follow. For us. The ones who buy the books in order to learn something.

Yeah, I'm somewhat at fault here. I had to do a lot of debugging because though I type well, I do much better when writing code than when transcribing from a book. And I made a lot of typos. Another one of my specialties. This always adds hours of fun when learning a new technical subject.

One thing that did annoy me though, was that after exploring a lot of cool things in the early chapters of the book, the authors jumped from some relatively simple examples right into a full-blown application, which then had to be tweaked further.

If you start out in good faith, and get it all right, you'll have to dump your own code and lay in theirs, or else invent the application on your own so you can keep up. And of course if you do that, your application won't match theirs and you'll be screwed anyway.

Nuff said there. The part that bugged me the most was at the end, in the testing section. The unit tests went OK. Then I moved to the functional tests, and using code that worked in the application, code written by the authors, the functional test failed. It wasn't the assertion violation shown in the book, no, it was a nil object error.

Don't know what or why. I just gave up here. Had to move along. The authors do not provide a final code download for the finished application. If I'd had that I would have dropped it in, but would only have come to the final annoyance, the section on integration testing.

Rather than having the reader work through this by running it, the authors just provide some text and describe what happens. Since "integration tests are a new feature in Rails 1.1", and "Integration tests are higher-level scenario tests that verify the interactions between the application's actions, across all controllers", it would have been ever so nice to have seen this part of the environment actually work. [10]

But no. Not in the lifetime of this edition. You just get to read about it.

One final festering figment of orneriness. And that is with the Instant Rails environment. Curt Hibbs is creator of this recommended installation technique. Maybe it's OK now, but I tried this several months ago and was unable to get it working.

I know it works, and it probably works far better today than an earlier version six months ago, but I couldn't get it to work for me, then. You don't need the Apache web server because Ruby on Rails has a simple server called Webrick built in, and though it's not efficient, it's very handy for development work. But Apache comes with Instant Rails. Whether you want it or not.

When I tried Instant Rails (remember, this was months and months ago), I had some kind of Apache problem popping up at me, even though I didn't need or want Apache. I also had a prior MySQL installation that Instant Rails didn't like. As I recall, I got the MySQL problem first, and then when I dumped the data from my tables and saved it, and uninstalled MySQL, Instant Rails didn't have that problem anymore, but decided to choke on something related to Apache. Maybe that was it.

Over and over I tried to configure it, but there isn't much you can do. Instant Rails is the sort of environment you just drop in, and it just works. Except...

If I was smarter or more experienced, things would have gone better, I know. I know it in my little heart of hearts. They would have. They would. But I've not led a pure enough life for that, and that route is closed to me, so I've stuck with Plan A. I started with the "One-Click Installer" [11] and upgraded across the internet, and that has worked fine. I'm tickled all to bits when things don't blow up in my face, and they haven't, with this route. It works. Yay!

So there you are. Let's try some concluding remarks then.

If you want a book to learn Ruby on Rails with, try the upcoming second edition of "Agile Web Development with Rails", by Dave Thomas and David Heinemeier Hansson, et al. [12] I still think that's the best, and most complete. I've only seen the first edition, and it is good. Edition two can only be better.

If you want a second book, try "Ruby on Rails: Up and Running", by Bruce Tate, Curt Hibbs. It's good, and will give you another perspective. Hope for a corrected and updated second edition too. The first edition is not truly great. Good, but not great.

---- references --------------------------------------------------------------------







[7] ("Agile", p. 58, first edition)

[8] ("Up and Running", p. 59)

[9] ("Up and Running", p. 58)

[10] ("Up and Running", p. 124)