Ri is the Ruby solution to this problem but the results are not always what you are expecting.

A Simple Enhancement for ri

One of the last features that I added was to make it possible for users to report inaccurate data. This feature was important to the community aspect of the site and is the bridge to get users into the membership system and to take some of the responsiblity for the content off of me.

I allowed the user to report an error on any event. To do this, I subclassed by Event model into LiveEvents (those you see) and EventCorrections, and then I created an administrative interface to accept or reject corrections in the EventCorrections. With Rails and Ruby this was brilliantly easy; using single table inheritance, it took less time to do than it had taken me to think about it and almost every point worked on the first pass.

But, and you knew there was going to be a “but” didn’t you, this somehow broke by search function for the site. Search had also been extremely simple to implement. I used Ferret in combination with the acts_as_ferret plugin for Rails. Somehow when I moves to LiveEvents from Events, searches that returned no results, broke, throwing mysterious exceptions without and traces.

I didn’t have a test for this case (I was still testing the base Events class – doh!) so I only saw it occassionally in development, but when I started seeing it in my production code, I tracked it down. I thought that it was from an upgrade to acts_as_ferret from a few weeks ago. Nope. I somehow caught

Here is the relevant bit of acts_as_ferret.

def find_by_contents(q, options = {}
   id_array = [] scores_by_id = {}
   find_id_by_contents(q, options) do |element|
     id_array < < id = element[:id].to_i
     scores_by_id[id] = element[:score]
   end
   begin
      if self.superclass == ActiveRecord::Base
        result = self.find(id_array)
      else
        # no direct subclass of Base --> STI
        # TODO: AR will filter out hits from other classes for us, but this
        # will lead to less results retrieved --> scoping of ferret query
        # to self.class is still needed.
        if id_array.empty?
          result = []
        else
           result = self.find(:all, find_options.merge(:conditions => ["id in (?)",id_array]))
        end
     end
  rescue
     logger.debug "REBUILD YOUR INDEX! One of the id's didn't have an associated record: #{id_array}"
   end

   # sort results by score (descending)
   result.sort! { |b, a| scores_by_id[a.id] < => scores_by_id[b.id] }

   logger.debug "Query: #{q}nResult id_array: #{id_array.inspect},nresult: #{result},nscores: #{scores_by_id.inspect}"

   return result
end

I don’t really understand the comment, “no direct subclass of Base –> STI TODO: etc.” It seems like using the AR filtering would be a good thing in all cases. Maybe this would break paginate? Anyway, I was seeing the logger.debug in dev, but I had misattributed it to some manual interventions that I had made in the db to remove some old data. Wrong.

The problem was that by changing my model to STI, the LiveEvent was not a subclass of ActiveRecord::Base, so instead of using the well-behaved return = self.find(id_array) my queries were now going through the ill-behaved return = self.find(:all, :conditions => ["id in (?)",id_array]). Calling find with any empty array returns an empty array. Calling find with condtions and a nil argument throws an exception.

Since this exception is caught, without doing anything worthwhile, the value of return is nil. Calling sort! on nil a few lines later throws an error, but since this code is in a plugin, there is no usable trace.

Lessons:

• Refactor the tests at the same time as code.
• Don’t allow errors in the logs. These always came up when I was working on something unrelated, so I never took the time to track them down.
• Anticipate the edge conditions. Seriously, 0 results is not unlikely.

1. Added return = [] to the rescue.
2. Wrap the sort in a test for return.nil?
3. Initialize return = [] at the top.
4. Add another condition within the block, if id_array.size == 0 return = [] elsif self.superclass ...

I actually did all of these in that order. They all worked in my tests. I decided on #4 because it was the most contained patch and had the added benefit of skipping the find(id_array) if the id_array was empty. Saving a db call isn’t something I would have gone out of my way to do without a strong motivation, but it was a side benefit.

It fails at this line:

update_attributes(:activated_at => Time.now.utc, :activation_code => nil)

This fails because there are a series of validations on saving the model. These on save validations on password_confirmation work (assuming correct values) when the user is created and when the password is changed, but fail on other saves of the user, particularly on activation, but would also fail if acts_as_authenticated had an edit method, or a last_seen method, or any other method that changed the user without also changing the password with a confirmation.

The rails wiki has a proposed fix, which works for activate only if not also using 2-way reversible encryption. The fix causes these validations to be attempted only if password_required, which in turn tests if password.blank? is false.

Two-way reversible encryption populates the model with the value of password, so that password.blank? is always false and password_required is always true.

I resolved the problem in acts_as_authenticated by making the following changes:

validates_presence_of :password_confirmation, 
                 :if => :confirmation_required? # not :password_required
validates_confirmation_of :password, 
                 :if => :confirmation_required? #ditto

And then I added the following:

after_save '@confirm_password = false'
	
def initialize(attributes = nil)
  super
  @confirm_password = true
end

def change_password(pass, confirm = nil)
  self.password = pass
  self.password_confirmation = confirm.nil? ? pass : confirm
  @confirm_password = true
end

protected

def confirmation_required?
  @confirm_password
end

Hope that helps.

One aspect of Rails that hasn’t received that much attention from outsiders is the quality of the community.

I have been hanging out on the Ruby on Rails mailing list (archive). It is a great resource. Essentially everyone who has ever contributed to Rails and representatives of most of the major sites that have been deployed using Rails are regular contributors. The newest newbies hang out right next to them. It is a fascinating community.

There are about a hundred of messages a day, and dozens of new threads. Topics range from I’m having trouble installing on my platform to this feature is planned for version 1.0 to submit a patch. This is the full gamut of possibilities. There is really very little snipping or flamage. The only heated discussions that I can remember in the 6 or more months that I have been on the list have been about the rails pluralization conventions.

The interesting thing is that this list is a real community. One of the reasons for that is the care that people have exerted over the list. In regard to someone suggesting downloading a pirated copy of Agile Web Development with Rails pdf, David Heinemeier Hansson says,

I didn’t expect someone to walk into our homes and slap us in the face like this.

There is a lot to respond to in this quote, which was probably made in anger, but it reveals a flash of what makes the community work. DHH, and the other principals of the community, have a sense of pride and ownership. They care about the community

If I can build that in only of a few of the factscollector communities, I will have been wildly successful.

Update: Sept. 26th. Martin Fowler points to the general friendliness of the Ruby community as a factor in its acceptance. I’d agree. In particular, I’d draw a comparison between Ruby and Perl. If someone asks a question to comp.lang.perl.misc that has either been asked before, is well documented, or just shows that the questioner hasn’t really done their homework, they will be shot down from five directions, added to killfiles, or ignored. The leading figures of the group will be doing this.

Ask the same kind of question in the Ruby on Rails group, people will fall over themselves to answer. If someone is a little rude, or terse, in their response, they’ll apologize.

This creates a culture of openness. People have the room to ask “dumb” questions, to question how things are done, and to propose new solutions.

I probably waited too long to start, both in general, and in this particular Ruby on Rails project. The general reasons are well known in the Agile Programing literature. Tthe existance of the test is a safety net. Having the test I can feel free to change to code and I don’t have to worry that I have broken something elsewhere in the code. The tests document what the code does, not what it ought to do. It occurs to me that tests are better than comments in this sense. Also, automatic tests are like double entry bookkeeping. It is easy to make a mistake. It is much harder to make two mistakes that exactly cancel each other out.

On factscollector, I waited too long because I found a couple of bugs in Rails. One was a documentation bug in ActionMailer and the other was in an interaction between controllers. Both that took me a while to track down, particularly because I was more suspicious of my own code than of the framework. (Why is that? Whenever I learn a new language, or a new tool, I am more suspicious of myself than I am of this completely unknown tool? That’s not my default in most areas of life.) Both of these bugs would have been easier to track down if I had had functioning tests earlier, if only because the domain of the problem would have been radcally circumscribed.

While researching these issues, I came across this post from Ben Griffiths, CTO of Reevoo.

He advocates a template for creating and naming tests that serves as documentation for what the application actually does. Examples are worth many words, here is one of my tests:

def test_should_return_user_to_login_template_on_incorrect_password login "bob", "not_correct" assert_template_has "login" end

The test is very short. It tests exactly one thing. The name says that thing. It says it in an obvious pattern and Ben offers up a Rake task that outputs these as a pass at documenting what the application does. Here is a segment of mine from my user controller.

user_controller should: - allow creation of new user on valid password - send mail on successful user creation - not send mail on bad password - not send mail on bad email - display flash on successful login - not allow existing user to login on incorrect password - return user to login on incorrect password - store logged in user in session

These are discrete areas of functionality. All of these are very small. The collection of all of the tests (that pass, anyway) is a concrete expression of what the application can do right now.

This has been a huge productivity boon for me. As I’m visualizing what the application will do, I’m writing the test names. The names of the tests are the specification. This is actually fun, so I do it and then the excitement drives me to fill in the test and since the tests fail, I have to write the code to make the tests pass.

Looking at the actions documented here, I think I could improve the specificity of these names and improve the clarity of my thinking and my design. Ben recommends the template “test_should_***_on_***”. If the all the tests are short and sweet, like my example, then the possibilities for creating a test that don’t test what they purport to test are minimal. If the tests fail, it is immediately obvious what the application isn’t doing correctly, without going into the code.

I followed through that tutorial and I thought I was pretty clued in to what was happening and why. So I jumped in to try it myself. Since the training log project has been kicking around in my mind the longest, I thought I would give that a go. In retrospect, this was probably a bad idea. I had done several fitful starts on this project and so I had an existing database schema and other architectural ideas, that maybe weren’t so easily adapted to an out-of-the-box Rails project. My second mistake was to install an update to Rails (0.11) between reading the tutorial and turning to my own work. This confused that analysis of the later problems no end.

The first gotcha that I encountered was that database schema. I had defined several Type tables that were used in other tables, there was a ActivityTypes table that listed all the different activity records that could appear in the Workouts table, a WorkoutTypes table that described the status of the workout (planned, library, or completed), etc. These tables may not ultimately be very useful in Rails, or maybe they will, but the problem is that I created these tables without following the ActiveRecord conventions – lower case, plural table names for objects, the primary key should be a sequence named id, and foreign keys should be named lowercaseforeigntable_id. Instead of wiping the slate clean, I went in and fixed these problems one at a time. The combination of these two, with the intervening update of Rails was a mess.

Once I started over with reasonable incremental development practices, I was sailing smoothly, except it appears that Rails (WEBrick server) doesn’t clean up from old sessions, and by old, I mean really old. I was getting NoMethodErrors on every page that I attempted. This didn’t make any sense, but Goggle handed me the answer here. It seems like my earlier testing on the tutorial was sticking around and my new framework wasn’t being read.

The third obstacle was really very minor. In Curt Hibbs follow up to his Rolling on Rails, Part 2 he alluded to using the Rails generator to create the entire scaffold of an application. He doesn’t make a detailed mention, but base on what he said, I assumed that the scaffold :workout line would automatically be added to my controllers/workout_controller.rb file. Not so.

Now after, a few hours of productive work, and another few unproductive hours, I have a working application. Everything else is just stepwise refinement.