Ruby as Poetry

Domain Specific Documentation

2008-03-24T13:00:00.000-07:00

I've often lamented poor documentation in libraries I've had to use. Even more troubling is a lack of proper documentation in my own code. Many times have I vowed to start every project with a flow-chart of all methods with their contracts, only to have it spiral out of control.

A problem with Rails is that it's so productive, the time you spend documenting your code can literally be something like the cube of the time you spend writing to the spec. Some wouldn't call this a problem - but it can lead to you iterating out ahead of yourself to the point where, if you're not careful, you'll end up with an unmaintainable mess.

The solution? RDoc.

RDoc lets you comment as you go. This can be as simple and useless as "this method does stuff" or a more formal contract for each controller action, such as:

# requires:
# - sessions[:username] is_valid_username
# produces:
# - @items_in_cart = ELEMENTS(user = sessions[:username], items U sessions[:cart] )
# - @username = sessions[:username]
# renders:
# - view : 'store#cart_view'
# failure_states:
# - redirect_to view : 'store#index'
def cart_view
...
end

It only takes a second to sketch up, and there's absolutely no question what the operation does and doesn't do.

The requires/ensures clauses are adapted from a RESOLVE-C++ method of design-by-contract. Just because it's an in-house research language doesn't mean you can't learn from it, right? However, Rails' MVC structure as well as the conspicuous absence of pass-by-reference requires some modification. I propose 'requires (things like params), produces (instance variables created), writes (to database), renders (which view), and fails_to (what does it do when the precondition isn't met?).' Fails-to seems like a bad fit for contract-based-design that should never, in theory, fail... but this is the web, and if there's a way for some of your code to break, then it will. The best thing to do is to define it explicitly.

Once you have all of these contracts written, it's trivial to get the sweet, sweet documentation from your code. Add the following to your ${RAILS_ROOT}/Rakefile:

Rake::RDocTask.new do |rd|
rd.rdoc_files.include("app/**/*.rb")
end

Then just ${RAILS_ROOT}/rake rdoc

Voila! Instant domain documentation.

The rest of the week: doing this stuff automatically from the top-down.

Drag and Drop

2008-03-24T12:59:00.000-07:00

So I was getting a 'nil object where didn't expect it' error attempting to use the drop_receivable_element helper while working through some tutorials. Yes, I'm going to school for English to be able to write sentences like that. Yes, I know it's a mistake.

The problem is that, like a lot of the magicks underlying Rails, many of the helper methods all call each other. At some point in the development process, after the writing of the above tutorial I assume, drop_receivable was modified to call some of the link helpers.

The assumption is that if you have such an ajax drop-able area, you're going to want to fire off a request to some controller somewhere, and so why not make the link mandatory? While that's all well and good, there should probably be some sort of dignified way to 'opt-out' of this sort of thing.

You can add a quick hack to get around it if you specify :url => '#' in the options hash. Mine looked like this:

<%= drop_receivable_element(:dropDIV , {:url => '#', :hoverclass => :hover}) %>

Also, I understand that we can strip out 'parameter punctuation' to make things more streamlined? I mean, I know that drop_receivable_element :dropDIV, :url => '#', :hoverclass => :hover might fit more into in-line text... but I always thought that the extra symbols were good to help break the code up a bit more and make it more maintainable.

Anyway, I'm going to be doing some more work later on this week to get drag-and-drop working in 2d space, the first step in getting a web-based, virtual tabletop off and running.

Rails, and contract-based design.

2008-03-11T12:21:00.000-07:00

I've just finished my first Rails web application (link) and now it's time for a debrief - since I've actually produced and deployed something, and thus, am not nearly as scrubbly as I once was. Since I actually have a blog now, hopefully that also serves to elevate me above plebeian status.

Rails is fast.: Your friends didn't lie to you. Rails is damn fast. I created the website in probably only two to three hours of actually sitting down and making keystrokes.
Rails documentation sucks.: RDoc is a wonderful, powerful, amazing tool for the creation of great web-based documentation. And Rails doesn't use it. The reason being because the biggest method in any class in any rails app is method_missing, since that's where all the magic happens, and that's really hard to make documentation for.
Rails lets you write some really bad code.: Rails is so amazingly productive, you'll get carried away by developing incrementally and iteratively. At least while you learn it, you'll have absolutely anemic models and bloated controllers with redundant, ugly, logic-filled views. This is not very Rails-like. Yet, if you're like me, you're so focussed on getting to the next milestone and getting the next iteration out the door that unless you've been drilled with good practices, you're likely to forget them.

So what's a developer to do?

Enter Ruby Design By Contract. (Note that, according to wikipedia, 'Design By Contract' actually might be a registered trademark, so use it with caution.) RDBC is available through gem, and it actually has a pretty good readme, so just do a "gem install rdbc ; gem_server" and read all about the spec. Done? Ok, good. Basically, rdbc allows you to create a number of pre and post-assertions that execute in your code, which is great if you're creating a library, say, and you need to unit-test it. But what about if you're creating a rails application, and you have all of this magicks going on that you need to keep track of?

That's where this next project will come in - I'm going to write a rails plugin that allows you to define, from a top-down perspective, everything in your application, which controllers require what inputs and what views they call, what methods are available to each of your method objects... everything.

The end result?

Domain-specific documentation. Fat models. Anemic controllers. Beautiful, #HAML-expressible views. An order of magnitude more productivity, and a logarithmic decrease in bugs.

Interested? Stay tuned.