Relevance - Relevance Weblog

The Power of Names

2009-10-20T12:16:00Z

Last week I had a great time at the Latin America Rails Summit. (Thanks to the organizers for inviting me!) During breaks in the action here and there, I spent time working on Tarantula, and for a lot of that time I was sitting with Chad Fowler and David Chelimsky. David was working on RSpec, and asked Chad and me for help coming up with a good name for a method. The ensuing conversation struck all of us as a great example of the power of good names.

It’s often very difficult to find just the right name for something in a program. It’s also hard to understand why names are so important. Names are just symbols, after all, and in some sense they’re arbitrary. Certainly the computer doesn’t care what name you use for something, as long as you’re consistent. And programmers are fairly good at dealing with arbitrary names; think of all the acronyms we use without ever thinking of what the letters stand for, and repurposed words like “bus,” “mask,” and “string,” with technical meanings that bear little resemblance to the original English meanings.

So if we can deal with non-optimal names just fine, and choosing good names is really difficult, it hardly seems worth it. But good programmers understand the value of names. This story illustrates how hard it can be to find just the right name, and also how good names can help you to understand your own program and domain in deeper ways.

Wrapping Assertions

David was working on RSpec’s built-in DSL for defining matchers. A matcher in RSpec is the object that actually tests a particular condition to determine whether or not it holds, along with a method that’s used to select the desired matcher. There was a time when creating a matcher was a bit cumbersome, but David and other RSpec contributors have made it much easier over time, and part of that is a little DSL. Here’s an example, from the RSpec docs:

Spec::Matchers.define :be_in_zone do |zone|
  match do |player|
    player.in_zone?(zone)
  end
end

That snippet creates a matcher called be_in_zone that checks whether a supplied player (the actual value, in traditional unit-testing parlance) is in the expected zone. With that matcher defined, a programmer can write an expectation in this form:

bob.should be_in_zone(3)

In some situations, RSpec needs to work with assertions defined for test/unit. That works just fine; when using RSpec with Rails, for example, you can use Rails’ custom assertions like assert_select and it just works. But RSpec users would like to be able to easily wrap an assertion in an RSpec matcher, so that their tests are more consistent.

That’s the feature David was working on: support in the matcher DSL for calling a test/unit assertion and mapping that to RSpec semantics. The matcher needs to call the assertion, determine the result, and report that result the way an RSpec matcher is supposed to.

David wrote the first version without thinking about names very much (just to get it working) and came up with the wrapped_assertion method, used like this:

Spec::Matchers.define :equal do |expected|
  match do |actual|
    wrapped_assertion(AssertionFailedError) do
      assert_equal expected, actual
    end
  end
end

Both test/unit and RSpec recognize three results of a check: success, failure, and error. Success is when everything happens as expected. An error occurs when the code under test (or perhaps the test itself) raises some unexpected exception. Failure, on the other hand, happens when the code all seems to work (in the sense of not raising any exceptions) but one of the expectations is not met. In test/unit, failure is indicated when an assertion raises AssertionFailedError.

So two of the three situations are indicated when an exception is raised; the distinction lies in which exception. The definition of wrapped_assertion is explicit about that: it takes an argument that is the exception class representing failure.

def wrapped_assertion(error_to_rescue)
  begin
    yield
    true
  rescue error_to_rescue
    false
  end
end

As you can see, the matcher is supposed to indicate success by returning true and failure by returning false. Any unexpected exception just bubbles out of the method, indicating an error.

When that was working, David checked it in and asked Chad and me for our thoughts about a better name than wrapped_assertion.

He started by explaining the situation and refreshing our memory about the semantics. We promptly threw out some possibilities: fail_when, fail_on, fail_on_raise … I don’t remember all of the suggestions, but I know those were in the mix. And I think we settled on fail_when_raises, because that made sense even if the parameter was optional and omitted: fail_when_raises will fail when any exception is thrown, whereas fail_when_raises(AssertionFailedError) will fail only when that explicit error is thrown.

That was that, we thought. It was dinner time, so we closed our laptops and forgot about the problem.

Keeping the Domains Straight

The next day, however, we found ourselves around a different table, back to working on our three different projects. David realized he wasn’t happy with the method name, for a subtle reason.

This is a method that bridges two domains: the test/unit domain and the RSpec domain. Inside the method, test/unit rules: we call an assert method and interpret the result. Outside the method, however, is the domain of RSpec. The method name needs to be expressed in RSpec terminology that’s appropriate for the situation.

The test/unit terminology of success, failure, and error does apply to RSpec, but not at the level of matchers. A match expression is not a complete expectation in RSpec; it only constitutes an expectation when matched with a should or should_not, like this:

actual.should match(expected)
# or
actual.should_not match(expected)

So the matcher either matches or not, and returns true or false to indicate that. The presence of should or should_not indicates whether that match was expected, and translates it to success or failure. (This allows a single matcher to handle both positive and negative expectations, as opposed to test/unit assertions, which tend to come in positive/negative pairs such as assert_equal and assert_not_equal.)

Method names including the words “fail” or “succeed” were letting the test/unit domain leak out of the method body. A better name would be expressed in RSpec terminology. We toyed with false_when_raises until Chad suggested match_unless_raises and we all knew it was right.

Deeper Understanding

At that point we all thought we were done, and I mentioned that it would be good to blog about the whole dialogue; many programmers don’t take names very seriously, and it would be good to show the real experience of three good programmers spending more than 5 minutes, in two separate conversations spread across two days, on a name for one simple method.

But the big payoff was yet to come. Once the correct name was in place, it helped David to see something important about his problem domain.

Let’s look at that original example again, now with the new name:

Spec::Matchers.define :equal do |expected|
  match do |actual|
    match_unless_raises(AssertionFailedError) do
      assert_equal expected, actual
    end
  end
end

There’s repetition there—the parallel structure of match and match_unless_raises—that is a clue to something wrong. David noticed it immediately and realized that match_unless_raises should be promoted to the same level of the API as match. Now the example is beautifully simple:

Spec::Matchers.define :equal do |expected|
  match_unless_raises(AssertionFailedError) do |actual|
    assert_equal expected, actual
  end
end

That’s all it takes to write a matcher that wraps a test/unit assertion.

A lot has been written about the importance of names in programming, including Tim Ottinger’s classic Ottinger’s Rules for Variable and Class Naming. Good names help us communicate with other programmers, and with our customers. The notion of the ubiquitous language that features so prominently in domain-driven design is based largely on the choice of good, meaningful, shared names.

But good names also reflect the clarity of our thinking, and help us to communicate with ourselves about our own thoughts. And when we get the names right, our code and the problem domain can speak clearly to us, revealing accidental complexity and the underlying simplicity we’re searching for.

Good names are worth the trouble.

The Case for Clojure

2009-10-19T18:52:00Z

The case for Clojure is richly detailed and well-documented. But sometimes you just want the elevator pitch. OK, but I hope your building has four elevators:

"Concurrency is not the problem! State is the problem. Clojure's sweet spot is any application that has state."
"Don't burn your legacy code! Clojure is a better Java than Java."
"Imperative programming and gratuitous complexity go hand in hand. Write functional Clojure and get shit done."
"Design Patterns are a disease, and Clojure is the cure."

Any one of these ideas would justify giving Clojure a serious look. The four together are a perfect storm. Over the next few months I will be touring the United States and Europe to expand on each of these themes:

"Clojure's sweet spot is any application that has state." At Oredev, I will be speaking on Clojure and Clojure concurrency. I will demonstrate how Clojure's functional style simplifies code, and how mere mortals can use Clojure's elegant concurrency support.
"Clojure is a better Java than Java." I will be speaking on Clojure and other Java.next languages at NFJS in Atlanta and Reston.
"Design Patterns are a disease, and Clojure is the cure." I will sing a siren song of Clojure to my Ruby brethren at RubyConf.
"Write functional Clojure and get shit done." At QCon, I will give an experience report on Clojure in commercial development. Our results so far: green across the board. Both Relevance and our clients have been pleased with Clojure.

Want to learn about all four of these ideas, and more? Early in 2010, I will be co-teaching the Pragmatic Studio: Clojure with some fellow named Rich Hickey.

If you can't make it to any of the events listed above, at least you can follow along with the slides and code. All of my Clojure slides are Creative-Commons licensed, and you can follow their development on Github. Likewise, all the sample code is released under open-source licenses, including

the sample code for Programming Clojure
a port of examples from Practical Common Lisp to Clojure
various examples from the blog

And remember: think globally, but act only through the unified update model.

Brian's Functional Brain, Take 1.5

2009-10-07T10:59:00Z

Last week, Lau wrote two excellent sample apps (and blog posts) demonstrating Brian's Brain in Clojure. Continuing with the first version of that example, I am going to demonstrate

using different data structures
visual unit tests
JMX integration (gratuitous!)
an approach to Clojure source code organization

Make sure you read through Lau's original post first, and understand the code there.

Data Structures

In a functional language like Clojure, it is easy to experiment with using different structures to represent the same data. Rather than being hidden in a rat's nest of mutable object relationships, your data is right in front of you in simple persistent data structures. In Lau's implementation, the board is represented by a list of lists, like so:

(([:on 0 0] [:off 0 1] [:on 0 2]) 
 ([:on 1 0] [:on 1 1] [:off 1 2]))

Each cell in the list knows its state (:on, :off, or :dying), and its x and y coordinates on the board. The board data structure is used for two purposes:

the step function applies the rules of the automaton, returning the board's next state
the render function draws the board on a Swing panel

These two functions have slightly different needs: the step function cares only about the state of adjacent cells, and can ignore the coordinates, while the render function needs both.

How hard would it be to convert the data to a form that stores only the state? Not hard at all:

(defn without-coords [board]
  (for [row board]
    (for [[state] row] state)))

You could write without-coords as a one-liner using map, but I prefer how the nested fors visually call out the fact that you are manipulating two dimentional data.

Without the coords, the board is easier to read:

((:on :off :on)) 
 (:on :on :off))

If you choose to store the board this way, you will need to get the coordinates back for rendering. That's easy too, again using nested fors to demonstrate that you are transforming two-dimensional data:

(defn with-coords [board]
  (for [[row-idx row] (indexed board)]
    (for [[col-idx val] (indexed row)]
         [val row-idx col-idx])))

So, with a couple of tiny functions, you can easily convert between two different representations of the data. Why not use both formats, picking the right one for each function's needs?

When performance is critical, there is another advantage to using different data formats: caching. Consider the step funtion, which uses the rules function to determine the next value of each cell:

(defn rules
  [above [_ cell _ :as row] below]
  (cond
   (= :on    cell)                              :dying
   (= :dying cell)                              :off  
   (= 2 (active-neighbors above row below))     :on   
   :else                                        :off  ))

The "without coordinates" format used by step and rules passes only exactly the data needed. As a result, the universe of legal inputs to rules is small enough to fit in a small cache in memory. And in-memory caching is trivial in Clojure, simply call memoize on a function. (It turns out that for this particular example, the calculation is simple enough that memoize won't buy you anything. Lau's second post demonstrates more useful optimizations: transients and double-buffering. But in some problems a cacheable funtion result is a performance lifesaver.)

If you use comprehensions such as Clojure's for to convert inputs to exactly the data a function needs, your functions will be simpler to read and write. This "caller makes right" approach is not always appropriate. When it is appropriate, it is far less tedious to implement than the related adapter pattern from OO programming.

Since multiple data formats are so easy, you can use yet another format for testing.

Testing

Brian's Brain is a simulation in two dimensions, it would be nice to write tests with a literal, visual, 2-d representation. In other words:

; this sucks
(is (= :on (rules (cell-with-two-active-neighbors))))

; this rocks
O..
...  => O     
..O

In the literal form above the O is an :on cell, and the . is an :off cell.

Creating this representation is easy. The board->str function converts a board to a compact string form:

(defn board->str
  "Convert from board form to string form:

   O.O         [[ :on     :off  :on    ]
   |.|     ==   [ :dying  :off  :dying ]
   O.O          [ :on     :off  :on    ]]
"
  [board]
  (str-join "\n" (map (partial str-join "") (board->chars board))))

The board->chars helper is equally simple:

(def state->char {:on \O, :dying \|, :off \.})
(defn board->chars
  [board]
  (map (partial map state->char) board))

With the new stringified board format, you can trivially write tests like this:

(deftest test-rules
  (are [result boardstr] (= result (apply rules (str->board boardstr)))
       :dying  "...
                .O.
                ..."

       :off    "O.O
                ...
                O.O"

       :on     "|||
                O.O
                |||"))

The are macro makes it simple to run the same tests over multiple inputs, and with liberal use of whitespace the tests line up visually. It isn't perfect, but I think it is good enough.

One last note: the string format used in tests is basically ASCII art, so you can have a console based GUI almost for free:

(defn launch-console []
  (doseq [board (iterate step (new-board))]
    (println (board->str board))))

JMX Integration

Ok, JMX integration is gratuitous for an example like this. But clojure.contrib.jmx is so easy to use I couldn't resist. You can store the total number of iterations perfomed in a thread-safe Clojure atom:

(def status (atom {:iterations 0}))

Then, just expose the atom as a JMX mbean.

(defn register-status-mbean []
  (jmx/register-mbean (Bean. status) "lau.brians-brain:name=Automaton"))

Yes, it is that easy. Create any Clojure reference type, point it at a map, and register a bean. You can now access the iteration counter from a JMX client such as the jconsole application that ships with the JDK.

To make the mbean report real data, wrap the automaton's iterations in an update-stage helper function that both does the work, and updates the counter.

(defn update-stage
  "Update the automaton (and associated metrics)."
  [stage]
  (swap! stage step)
  (swap! status update-in [:iterations] inc))

If you haven't seen update-in (and its cousins get-in and assoc-in) before, go and study them for a moment now. They make working with non-trivial data structures a joy.

You might disagree with my choice of atoms. With a pair of references, you could keep the iteration count exactly coordinated with the simulator. Or, with a reference plus an agent you push the work of updating the iteration count out of the main loop. Whatever you choose, Clojure makes it easy to both (a) implement state and (b) keep the statefulness separate from the bulk of your code.

Source Code Organization

Lau's original code weighed in at a trim 67 lines. Now that the app supports three different data formats, a console UI, and JMX integration, it is up to around 150 lines. How should we organize such a monster of an app? Two obvious choices are:

put everything in one file and one namespace
split out namespaces by functional area, e.g. automaton, swing gui, and console gui

I don't love either approach. The single file approach is confusing for the reader, because there are multiple different things going on. The multiple namespace approach is a pain for callers, because they get weighed down under a bunch of namespaces to do a single thing.

A third option is immigrate. With immigrate you can organize your code into multiple namespaces for the benefit of readers, and then immigrate them all into a blanket namespace for casual users of the API. But immigrate may be too cute for their own good.

Instead, I chose to use one namespace for the convenience of callers, and mutilple files to provide sub-namespace organization for readers of code. I mimiced the structure Tom Faulhaber used in clojure-contrib's pprint library: a top level file that calls load on several files in a subdirectory of the same name (minus the .clj extension):

lau/brians_brain.clj  
lau/brians_brain/automaton.clj
lau/brians_brain/board.clj
lau/brians_brain/console_gui.clj
lau/brians_brain/swing_gui.clj

I also used this layout for clojure-contrib's JMX library.

Parting Shots

Over the course of Lau's two exampples and this one, you have seen:

an initial working application in under 100 lines of code
transforming data structures for performance optimization
transforming data structures for readability
a second (console) gui
optimizing the Swing gui with double buffering
optimizing with transients
visual tests
easy addition of monitoring with JMX

And here are some things you haven't seen:

classes
interfaces
uncontrolled mutation
broken concurrency

Would it be possible to write a threadsafe Brian's Brain using mutable OO? Of course. Is there a benefit to doing so? I would love to hear your thoughts on the subject, especially in the form of code.

NFJS, the Retro (Twin Cities Edition)

2009-10-06T12:44:00Z

We had a terrific conference retrospective this weekend at the Twin Cities NFJS show. Eight people participated, with me facilitating. The conversation was good, and everyone left excited to implement the SMART goals that we chose.

As usual, we followed the basic structure from the Agile Retrospectives Book: Setting the Stage, Gathering Information, Generating Insights, Deciding What To Do, and Closing.

Setting the Stage

The NFJS conference retro is an odd beast: a sixty-minute retro embedded in a ninety-minute talk about using retros in your own organization. This poses a few special challenges:

The team needs to have a working agreement to occasionally "go meta" and talk about the mechanics of the retro during the retro. This risks reducing the value of the retro, but so far attendees have found it effective.
The team isn't really a team: it is a subset of the conference attendees thrown together for the first time to do the retro. So, the facilitator has to choose the activities in real time to match the size and composition of the group.

Sticking to the time box, we covered these ground rules in the first five minutes.

Gathering Information

To gather information, we used the team radar activity from the book. A few minutes of brainstorming identified about ten possible items to rate. That is too many to actually rate, so we used dot voting to narrow down to four items. Each participant used a Sharpie to make three dots next to the items they considered most important. As usual, the moving about the room helped people get engaged physically and mentally.

The items and their individual rating (1=worst, 10=best) follow:

meaningful content: 8, 7, 8, 7, 7, 7, 7
speaker quality: 9, 8, 8, 8, 8, 8, 9
track organization/session selection: 7, 8, 6, 6, 6, 6, 5
price/value: 8, 7, 6, 6, 8, 7, 6, 8

These numbers are quite high; overall possibly the highest I have seen at a conference retro. Also, the lowest scores were on track organization. When selecting talks for a conference it is almost impossible to please everyone, so while the scores were lower I was not optimistic about finding a useful recommendation. (Note that as the facilitator I kept these musings strictly to myself during the retro!)

Generating Insights

To generate insights we used the learning matrix. This exercise uses four quadrants (happy/sad/ideas/appreciation) to guide brainstorming. In the interest of space I will not reproduce the matrix results here: the information would be meaningless without pages of explanatory text.

Unusually, the "ideas" section filled up first. In fact, to hit the time box we didn't even manage to fill the other quadrants.

Deciding What To Do

To keep to our sixty-minuted time box, we agreed to dot vote for two items on the ideas list, and convert them to SMART goals. A SMART goal nees to be Specific, Measurable, Achievable, Relevant, and Timely.

We ended up selecting these goals:

By February 2010, update the website and printed materials to include a single-line of text describing the "recommended audience." Free text might seem dumb compared to some kind of tagging, and it is delibarately so. We started to discuss a system of categories and realized that this would make the goal more complex, and therefore less likely to be implemented. Keep it simple.
By February 2010, run a birds-of-a-feather (BOF) session titled "What To Do on Monday!" Everyone agreed that the conference talks were inspiring, and included ideas that could create massive improvements back at the day job. But massive improvements are often beyond the immediate control of conference attendees, and it is frustrating to go back to work on Monday and not be able to start a new practice. The BOF will allow attendees and speakers to look across all the conference topics and generate a list of bite-sized ideas. If the BOF goes well, we will use it to generate an outline for a formal talk.

February 2010 might seem like a long way off, but since the retro was a breakout team that did not include the people who would actually have to implement the recommendations, it seemed wise to allow the work to be done during the winter off-season for the NFJS tour.

Closing

To close the retro, we did a quick thumbs up/down/sideways check to see if the participants found the retro useful. Votes were seven up, one sideways.

All in all, a good sixty minutes. I am excited about implementing the new ideas, and I think that the regular recurring nature of NFJS provides a great opportunity to close the feedback loop faster than at a conference that runs less frequently.

10 Must-Have Rails Plugins and Gems (2009 Edition)

2009-09-30T11:55:00Z

When Paul Graham wrote that the “list of n things” is a degenerate case of the essay, our first thought was “Wow! That’s for us!” And we’re going one step farther: we’re recycling an old “list of n things” essay from last year.

Seriously, we’ve been thinking of revisiting 10 must-have Rails plugins for a while now. There is a place for lists like that, and the Rails plugin and add-on space has been moving quickly. We are always looking for better ways to do things, so we try out a lot of the plugins that come along. Our list of favorites—the ones that we use on almost every project—is almost completely different than last year’s model.

There’s one important change in focus: the plugins and gems that are solely related to testing are gone from this list. Of course, that doesn’t mean we’re down on testing. On the contrary, we built RunCodeRun because we think testing is so vital. We’re saving the testing tools for the RunCodeRun blog; we’ll be writing another degenerate essay there as a counterpart to this one.

There are numerous other plugins we use for special needs, such as PDF generation or attachment handling. But our favorites are the ones that we use on almost every project. So here they are, along with brief comments explaining why you want to check them out:

Inherited Resources: eliminates most of the boilerplate code from our controllers. (The new controller responder feature in Rails 3 is similar in intent.)
Formtastic: takes most of the pain out of writing the markup for HTML forms. (Together, Inherited Resources and Formtastic make a nice alternative to scaffolding frameworks like Streamlined and ActiveScaffold.)
CapGun: provides easy build notifications (see this previous post for more info).
Faker: helps us generate fake data. We use it for testing, but mostly for providing demo data for development and staging environments.
Clearance: feature-rich authentication and signup.
Safe ERB: helps ensure that our apps are not vulnerable to cross-site scripting attacks. (We look forward to similar functionality being baked into Rails 3.)
RedHill on Rails Core: we use this primarily to declare foreign key references in our database schemas. Telling the database about table relationships adds a small cost to our projects, but we’ve found that the benefits outweigh that cost. (It’s unclear where this plugin lives at the moment, but there are numerous forks of it on GitHub.)
RPM: Rails Performance Management from New Relic; wonderful for discovering and diagnosing performance problems.
will_paginate: the nicest, easiest pagination plugin we’ve seen.
hoptoad: great, customer-friendly notifications about exceptions that happen in the app.

Don’t reinvent the wheel! Use these plugins (or others like them), and definitely consider contributing to them if they fall short of what you need!

Quick and Easy Logging with LogBuddy

2009-09-23T12:15:00Z

Good logging is crucial for effective problem diagnosis in production. Plus, easy logging remains a terrific debugging technique during development. As helpful as “real debuggers” are, sometimes a debugging log statement is exactly what you need to find a problem quickly.

LogBuddy is a little gem that makes good logging easier. It helps even in Rails, which already has good logging support, and it’s a bigger help when building gems and standalone Ruby apps, where you have to start from scratch with logging.

What does LogBuddy do for you that Rails doesn’t already? There are numerous small features, but here are the big ones:

It ensures that logger is available everywhere, not just in classes that extend parts of the framework.
It makes it extremely easy to add informative debugging messages with annotated output and full exception info.

Installing and Adding LogBuddy to Your Project

To install the latest release of LogBuddy, just install the gem:

$ gem install relevance-log_buddy --source http://gems.github.com/

Then add a require 'log_buddy' statement to your app. If it’s a Rails app, it’s best to add this to environment.rb:

config.gem 'relevance-log_buddy',
           :source => "http://gems.github.com/", 
           :lib => "log_buddy"

Finally, initialize LogBuddy. In Rails apps, we usually put this in config/initializers/logging.rb:

LogBuddy.init

(You can pass some options to LogBuddy.init; we’ll get back to that in a bit.)

LogBuddy creates and initializes a logger for the app to use. In Rails apps, it simply uses RAILS_DEFAULT_LOGGER unless you tell it differently.

Using LogBuddy

LogBuddy mixes a couple of methods into every object in the system: logger and d. Here’s how they work.

The logger method is no surprise at all. It simply returns the Logger instance, and you can log by calling debug, info, warn, error, or log methods on it. LogBuddy’s logger doesn’t usually do anything special; the benefit is that, since it’s mixed into Object, it’s available everywhere, automatically. (In a typical Rails app, there are numerous contexts where logger doesn’t work, and you have to explicitly use RAILS_DEFAULT_LOGGER.)

My personal favorite LogBuddy feature is the d method. Like logger, it’s available everywhere. But the d method is designed just for debugging messages. You can call it with an explicit string, or with some object you want to see the value of:

d "FINISHED PARSING"
d some_exception
d result

Strings are logged the same way logger.debug would do it. Exceptions are logged with all of the information you might want: the message, exception class name, and backtrace. Finally, if you pass any other object, d calls that object’s inspect method and logs the resulting string.

Where d really shines is when you want to log several values at once, with annotations to distinguish them. Just pass a single-line block to d, like this:

d { first; current; last}

That produces these three log lines:

first = "foo"
current = "bar"
last = "baz"

The values you log can be any Ruby expression:

d { 3; name; @model; RAILS_ENV; options[:limit] }

and you’ll get just what you want out of that:

3 = "3"
name = "primary"
@model = #<Contact id: 14, name: "Joe">
RAILS_ENV = "development"
options[:limit] = 5

There are some restrictions if you use this feature. The entire call to d must fit on one line, and you must use the curly-brace style of block, rather than the do/end style. Finally, if you want to log multiple values, separate them with semicolons, not commas.

(You may be wondering how LogBuddy accomplishes that trick. The answer is left as an exercise for the reader … especially since there are some hints in the restrictions just mentioned. Of course, you can always read the source.)

LogBuddy Initialization Options

The LogBuddy.init method takes an options hash. Here are the permissible options:

:logger – you can supply a logger instance for LogBuddy to use. If you don’t supply one, LogBuddy uses RAILS_DEFAULT_LOGGER if it’s defined; otherwise, it creates a new logger that writes to standard output.
:log_to_stdout – by default, messages from the d method are logged (using logger.debug) and also written to standard output. Set this option to false to only use the logger.
:disabled – set this option to true to turn off the output from the d method. It’s common to set it this way:
LogBuddy.init :disabled => Rails.env.production?
:log_gems – if you set this option to true, LogBuddy watches gem activation and logs information about each gem. This can be useful for tracking down gem activation errors

Try It Out!

LogBuddy is really easy to set up, and then it’s there when you need it most: when you’re focused on a problem and just need to get the details quickly. Please try it and let us know what you think!

Easy Build Notifications with CapGun

2009-09-16T12:14:00Z

Most of us get notified about lots of little events on our projects: Commits, build failures (and fixed builds), and runtime exceptions, for example. But deployment is where the rubber meets the road on web development projects. Deployment to staging means new functionality to try out and test, and of course deployment to production is even more important.

CapGun is a gem we use to send email notifications whenever we deploy one of our projects. It works with Capistrano and uses ActionMailer to let every interested party know when a deployment happens.

Here’s how to work with CapGun in a Rails project. Add this to config/environment.rb:

config.gem 'relevance-cap_gun', 
           :source => "http://gems.github.com/", 
           :lib => "cap_gun"

Then install and unpack the gem:

$ rake gems:install
$ rake gems:unpack

Finally, edit your deployment script (usually config/deploy.rb) and add this:

require File.join(RAILS_ROOT,
                  Dir["vendor/gems/relevance-cap_gun-*/lib"].last,
                  'cap_gun')

set :cap_gun_action_mailer_config, {
  :address => "smtp.gmail.com",
  :port => 587,
  :user_name => "grey-goo@example.com", # deploy bot email address
  :password => "outtacontrol",  # deploy bot email password
  :authentication => :plain 
}

set :cap_gun_email_envelope, {
  :recipients => %w[fooproj-devs@example.com fooproj-mgr@example.com], 
  :from => "Foo Project Deployment Bot <grey-goo@example.com>"
}

after "deploy:restart", "cap_gun:email"

We usually use GMail as our MTA for this purpose, and CapGun includes support for secure, authenticated email connections so that you can do the same. It’s best to create a special-purpose, throwaway email account just for things like this; that way there’s little risk in putting the email password in the project deployment script. (But there’s also nothing stopping you from reading it from another file that’s not checked into source control, just like you would do with your production database passwords. The deploy.rb file is just Ruby code, after all. And if the source is going to be in a public repository, you should definitely do that.)

The deployment email has a brief summary at the top (in fact, the subject often tells you all you need to know). But there are useful details in the body. Here’s an example of what you might see from the configuration above:

From: Foo Project Deployment Bot <grey-goo@example.com>
To: fooproj-devs@example.com, fooproj-mgr@example.com
Date: Tue, 15 Sep 2009 17:27:57 -0400
Subject: [DEPLOY] fooproj deployed to production

fooproj was deployed to production by george at September 15th, 2009 5:27 PM EDT.

Nerd details
============
Release: /var/apps/fooproj/releases/20090915212721
Release Time: September 15th, 2009 5:27 PM EDT
Release Revision: 69246739f2a1cbcef5ca76f1842c21849db7778a

Previous Release: /var/apps/fooproj/releases/20090915194707
Previous Release Time: September 15th, 2009 3:47 PM EDT
Previous Release Revision: 9ceb19b1777470d1d5133f433fdd5d1873c7a4c0

Repository: git@github.com:foocorp/fooproj.git
Deploy path: /var/apps/fooproj
Domain: fooproj.example.com
Branch: main

Commits since last release
====================
d37a15c:who put a blink tag in here?
f1b603e:Added favicon

Setting up CapGun only takes a few minutes, and you’ll love the increased visibility into your team’s deployments. (And even if you’re a team of one, you’ll appreciate having the emails as a record of your deployments.) Try it out, and let us know what you think!

Keep Models out of Your Views' Business! (Part 2)

2009-09-09T14:03:00Z

Last week, I wrote about using Rails’ I18N facilities to break dependencies between your models and views, by changing how model and attribute names are displayed. But there’s another place where the implementation of models sometimes peeks through into views: validation error messages.

Depending on how you use them, Rails’ error message helpers may insert attribute names into messages, and the changes from last week will take care of that automatically. But it goes farther than that. Often, validation error messages express things in a way that is not appropriate for end users. The usual solution is to override the default messages with :message => '...' options on the validation declarations. But again, that means the model is actively involved in presentation issues, and we’d like to avoid that if possible.

Whole plugins have been written to try to solve this problem, but Rails internationalization support has made it much easier. When validation error messages have to refer to the name of a model class or attribute, they will use the locale definitions we’ve already supplied. And it turns out that they look in the locale for error message text, too.

Overriding Validation Error Messages

Last week, we used a typical Rails example: a blogging app with a model called Post with attributes title and body. (And we used I18N to relabel Post as Article, and title as headline.) Let’s continue with that example, assuming this declaration in Post:

validates_presence_of :title

The default error message (with the re-labeling we’ve already done) is “Headline can’t be blank.” How would we change that to something friendlier, like “Headline should not be empty; please supply one”?

Let’s add a little more to en.yml—an “errors” section that includes customized validation error messages:

en:
  activerecord:
    # models and attributes sections carried over from
    # previous article
    models:
      post: "Article"
    attributes:
      post:
        title: "Headline"
    # errors section is new
    errors:
      models:
        post:
          attributes:
            title:
              blank: "should not be empty; please supply one"

We’re now several levels deep in this YAML structure, but it should be fairly easy to follow. Under activerecord.errors there’s a section for models, within which we find our model (post). Of its attributes we’ve supplied a custom error message for the title attribute; in particular, we’ve customized the blank message.

With that change in place, the error messages will read as we’d like them to, with no change to the model or the views.

Note that we restricted this change to just the title attribute of Post. If we wanted to change all “can’t be blank” messages for all attributes of Post, we could do that as well:

en:
  activerecord:
    errors:
      models:
        post:
          blank: "should not be empty; please supply one"

Finally, if we wanted to make the change across all the models, here’s how:

en:
  activerecord:
    messages:
      blank: "should not be empty; please supply one"

Which Messages Can I Override?

You can see the current default messages in the source code for the activerecord gem; just consult the file lib/active_record/locale/en.yml. But here’s the entire list, mapped to the validation methods that use them. (Some validations use different messages depending on the circumstances.)

<dl>

validates_acceptance_of

:accepted (“must be accepted”)

validates_associated

:invalid (“is invalid”)

validates_confirmation_of

:confirmation (“doesn’t match confirmation”)

validates_exclusion_of

:exclusion (“is reserved”)

validates_format_of

:invalid (“is invalid”)

validates_inclusion_of

:inclusion(“is not included in the list”)

validates_length_of

:too_short (“is too short (minimum is {{count}} characters)”)
:too_long (“is too long (maximum is {{count}} characters)”)

validates_length_of (with :is option)

:wrong_length (“is the wrong length (should be {{count}} characters)”)

validates_numericality_of

:not_a_number (“is not a number”)

validates_numericality_of (with :odd option)

:odd (“must be odd”)

validates_numericality_of (with :even option)

:even (“must be even”)

validates_numericality_of (with :greater_than option)

:greater_than (“must be greater than {{count}}”)

validates_numericality_of (with :greater_than_or_equal_to option)

:greater_than_or_equal_to (“must be greater than or equal to {{count}}”)

validates_numericality_of (with :equal_to option)

:equal_to (“must be equal to {{count}}”)

validates_numericality_of (with :less_than option)

:less_than (“must be less than {{count}}”)

validates_numericality_of (with :less_than_or_equal_to option)

:less_than_or_equal_to (“must be less than or equal to {{count}}”)

validates_presence_of

:blank (“can’t be blank”)

validates_uniqueness_of

:taken (“has already been taken”)

</dl>

Interpolating values

You probably noticed that some of the default messages contain the string {{count}}. Validations that use some threshold value pass that value into the I18n library as the option count, and I18n interpolates the count value into the message string.

In addition to count, all of the validations supply three other values that can be interpolated: model and attribute (the model and attribute names, already humanized as discussed in part 1) and value (the erronenous value of the attribute). You can write your error messages to make use of any of those values, using the same double-curly-brace syntax.

Writing custom validations

If you write your own validation methods, whether just for your project or in a plugin, you should make use of the same mechanisms.

When a validation detects an error, it reports that error by calling the #add method on the errors object. Here’s an example (taken from validates_inclusion_of, and slightly modified to make more sense out of context):

record.errors.add(attr_name, :inclusion, 
                             :value => value, 
                             :default => options[:message])

The first parameter is the name of the attribute being validated. Second is the symbol that’s used to look up the default message text from the I18n message repositories. Finally there’s an options hash, which includes the current attribute value (for possible interpolation into messages) and any new message text that may have been supplied directly on the call to validates_inclusion_of.

(That last bit is somewhat confusing; the option to add is called default, but it’s actually a specific override. That bit of weirdness is there to maintain some internal compatibility for the benefit of plugins that were written for older versions of Rails. I wouldn’t be surprised to see that cleaned up in Rails 3, although for now it still works the same way.)

All you need to do in your custom validation is to use the #add method in the same way, and supply default error message text in a message repository, under the en.activerecord.messages key. You can do it directly in config/locales/en.yml, like this:

en:
  activerecord:
    messages:
      bozo: "can't be ridiculous"

Plugins and gems can supply their own YAML file. They just need to tell Rails about it by pushing the file path onto I18n.load_path.

Conclusion

As I said last week, the fact that Rails uses model and attribute names in views isn’t a bad thing; it’s a useful convention that helps developers move quickly. The test of a framework like Rails is how easy it is to break those links when you need to. Rails’ internationalization support makes it easy to solve this particular problem, with the added benefit that it makes your application easier to localize, should you need to go down that path.

I’ve completely stopped overriding validation error messages directly in the model code. You should, too!

Keep Models out of Your Views' Business!

2009-09-02T12:09:00Z

One of the core goals of the MVC architecture is to separate the presentation of a model from its implementation and semantics. And yet Rails, out of the box, takes the representation of models—even the names of tables and columns in the database—right through to the user. The default behavior, for form labels and other places where models and attributes are referred to, is simply to use the name of the model or attribute.

Does this mean Rails’ implementation of MVC is broken? Not at all! My favorite definition of “architecture” in software is “the set of decisions that will be hard to change later.” And the best architectures are the ones that keep that set small, allowing developers to move quickly without fear of being boxed-in later in the project. Rails uses its default behavior to let you move quickly, but leaves your options open for changing that behavior later.

I think Rails’ defaults work really well in most cases. After all, we should be working with a domain language that we share with customers and domain experts, so it’s likely that our schema and models will use names that are appropriate for presentation. Nevertheless, it’s common to reach a point where the user interface needs to use different terms for some of the domain concepts.

So let’s see how Rails can help. Assume we’ve developed the “canonical” Rails application, a blogging engine. The primary model is called Post, and each post has a title and body. And then, the customer decides that the users will prefer writing “articles” rather than “posts”, and “headlines” instead of “titles”.

What can we do?

Breaking the Link: The Obvious Ways

The most obvious, brute-force solution is to avoid the defaults, instead supplying literal names in all of our views. While there are places where it will be appropriate to supply literal labels, this option should be reserved for specific places where the context requires a different label. Using this approach to change labels throughout the application would be way too much work, and create a maintenance nightmare.

You could actually change your model—rename the table, or column, along with every place that name appears in your Ruby code. But that approach would be tedious and error-prone if the name were central to your model. More importantly, it would be a mistake to change the domain model understood by those involved in the project just to satisfy presentation constraints. It’s at this point that the MVC architecture needs to pull its weight by helping you deal with this problem.

Digging a little deeper, you realize that the places in ActionView that use model and attribute names (e.g., the label helper) transform them to “human” form first, removing underscores, adding spaces, and capitalizing appropriately. They do that by calling the human_name method (for model names) and human_attribute_name (for attributes). Every ActiveRecord model inherits those methods from ActiveRecord::Base. So one answer is to override those methods. That’s much better than either of the other options, but it’s still not very good. If you solve your problem this way, the model will be actively involved in presentation issues. We want to work with the MVC architecture, not against it.

Breaking the Link: The Right Way

The answer to our problem can be found in the documentation for ActiveRecord::Base#human_attribute_name:

This used to be depricated in favor of humanize, but is now preferred, because it automatically uses the I18n module now.

We can use Rails’ internationalization support to supply the new names we want to present to users. Think about your current problem as specifying the English localization for your application.

If it’s not already there, create the file config/locales/en.yml, with the following contents:

en:
  activerecord:
    models:
      post: "Article"
    attributes:
      post:
        title: "Headline"

Under the en.activerecord key there are two sections that define presentation names for the locale: models contains names for models, and attributes contains names for … well, I think you get the idea. So in our example, the new name for a post is “Article”, and the new name for a post’s title is “Headline”. Note that you specify attribute names in the context of a model class, so if there were another title attribute in your system on a different model class, it would not be affected.

Suddenly, throughout your application, those changes will take effect. You can still supply different labels in particular contexts as needed, but the default is to use the names in the locale file.

Update: As commenter Tim Watson pointed out, it’s not currently automatic everywhere. It does automatically happen in error messages, but not in labels (making labels handle this automatically is planned for an upcoming Rails point release). You can supply the proper label text on your own (using the human_attribute_name method). If you’re using custom FormBuilders, you can easily encapsulate this change; otherwise, see commenter Priit Tamboom’s solution for doing a quick monkeypatch of the label helper until Rails handles it properly.

As you may have gathered from the documentation excerpt above, you should use Post.human_attribute_name('title') instead of calling humanize on an attribute name when writing views. Likewise, you should use post.class.human_name rather than post.class.name.humanize or the literal 'Post' for model class names.

Also, associations are treated as attributes, rather than inheriting the new name of their target model. So if some model had an association to multiple posts, you would need to define an attribute renaming in the appropriate model; it would not automatically be called “Articles”.

Finally, this approach doesn’t deal with controller names in URLs; for that, you should modify the routes in config/routes.rb.

More To Come

There’s more to this story, because there’s another place where your models peek through into the user interface in undesirable ways. I’ll address that in a follow-up post.

RunCodeRun Basic Plan Now Available

2009-09-01T07:00:00Z

We've been building your open source projects for about a year now. Thanks to the experience we've gained from our wonderful commercial beta users you too can let us take care of your continuous integration needs, no matter what they are -- as long as you use GitHub.

The Premium and Walk Among the Gods plans, announced earlier this month provide a dedicated server for each account. We're pleased to announce that the RunCodeRun Basic Plan is also available. Targeted at solo developers, the Basic Plan costs $19 per month and supports up to three private projects. Unlike our other plans, the Basic Plan private builds run on shared RunCodeRun build resources.

With three plans to choose from, we know that one of them is just right for you. Sign up and focus on delivering valuable software instead of on maintaining CI servers.

Tarantula Supports Ruby 1.9

2009-08-25T12:12:00Z

We’re excited about Ruby 1.9. It’s fast and stable, and brings nice improvements for programmers. But there are obstacles to adoption—mostly gems, plugins, and tools that don’t support 1.9 yet.

So we’re working on the things Relevance maintains, to get them on board. We’re doing it by dog-fooding: We’ve got one customer project that we’re actively testing on both 1.8 and 1.9 (although deployment is still on 1.8 for the moment). That’s helping us see where the holes are, so we can fix them. We’re already working on Ruby 1.9 support for RunCodeRun, and investigating the best way to interface rcov with 1.9.

Now one more piece of the puzzle is in place: on our last open-source Friday, Chad upgraded Tarantula to support Ruby 1.9. If you’re trying out Rails on 1.9 (or even if you aren’t), get the latest version (0.2.1) of tarantula from github:

gem install --source http://gems.github.com relevance-tarantula

Then add the plugin to your app and add some fuzz-testing goodness to it!

The Longevity of "Enterprise" Tools

2009-08-19T13:15:00Z

During the recent erubycon conference, there was a lot of twitter traffic from attendees about how great the conference was. One who did not attend wondered if a conference discussing “Ruby in the enterprise” was wishful thinking or reality?.

Sorry if this disappoints anyone, but there was almost no wishful thinking, and a lot of reality. But there’s a third option: planning next moves. There was a lot of discussion about how to promote Ruby effectively in enterprises that aren’t already using it—not because Ruby is the be-all, end-all of programming (it’s not) but because we have all found it helpful across a wide variety of programming tasks, and we think it is a good antidote for the more common, “enterprisey” tools that often bring more bad than good to a project.

During a panel discussion right after my keynote (Why “Enterprise Tools” are Bad for the Enterprise), someone asked “What do we say to a manager who doesn’t trust open-source tools to still be around in a few years?”

Something snapped in me—I’d heard that same question one too many times. Commercial tools are available solely based on their customers. If the tool gets enough customers, the tool continues. Otherwise, it will all disappear. And it must disappear, given the nature of the software business.

There are three scenarios (with variations) for new software development tools, and all are common:

get enough customers to be profitable, and continue for many years.
get enough customers to look viable, get purchased and see the tool squashed or sidelined by the new owners.
get just a few customers, and have your board shut you down.

When you choose a commercial tool, you’re making a bet that enough other people will purchase it to make it viable, and that it won’t be purchased and shut down by a competitor.

When you choose open-source tools, there is no monetary pressure on the toolmaker to continue; only community pressure. It’s much easier (and cheaper) to bring community pressure. Additionally, even if the toolmaker chooses not to continue, the community can keep the tool alive. Many open-source development tools that have long since dropped from most people’s radar (think Tcl, for example) still have thriving communities that actively support the tools and help each other with difficulties. With a proprietary tool, the legal structures surrounding it virtually guarantee that the tool will die if the vendor loses interest.

In every respect, open source tools have a better chance of surviving than their commercial cousins. Sure, some of those commercial tools will be viable for a long time, but most won’t. Whereas most open source tools will be around for a long time. Open source tools actually diminish risk, not enhance it.

Anyway, getting back to the panel question at erubycon: I decided it was time for action, because this is such an easy point to refute with just a little preparation.

So I volunteered to play scribe during the party that evening, and I spent much of the party sitting in a chair with a pad and pen, while attendees helped me remember “enterprise tools” that have come and gone. We built a list of commercial, “enterprise” software development tools of one sort or another that were commercially viable no longer ago than 1995 (when Java first hit the scene) but which are now “dead”. (“Dead”, for purposes of this list, means either that there is no longer commercial support for the tool, or that there has been no significant new development on the tool in the past five years.)

It’s a long list.

The point of this is not to prove that open-source tools are better than proprietary tools (obviously I think they are in most cases, but this list won’t prove it either way). The point is to show clearly that there is no guarantee that a tool will still be around and supported after a few years, proprietary or not.

I’m sure there are other tools that we didn’t think of. I’m equally sure that some of the tools currently on the list are actually alive; the fact that attendees at erubycon haven’t heard of a tool for a while doesn’t mean it isn’t still being maintained and supported somewhere. (Here’s a good example. I thought of a tool that seemed like an open-and-shut case for this: NetDynamics, the original Java application server. A little research shows that it was purchased by Sun, and some of its code formed the basis for the iPlanet application server, which was later called Sun ONE, and then the Sun Java Enterprise System, and is now called GlassFish. Nevertheless, I strongly doubt that old apps written for NetDynamics would run on GlassFish, and I’d be interested to know whether there was ever a clear migration path for NetDynamics customers.)

So I’m starting the task of double-checking that list. If you’re interested in helping, send me email! I’ll blog about the results here.

Rifle-Oriented Programming with Clojure

2009-08-12T23:58:00Z

Any comparison of hot JVM languages is likely to note that “Clojure is not object-oriented.” This is true, but it may lead you to the wrong conclusions. It’s a little like saying that a rifle is not arrow-oriented. In this article, you will see some of the ways that Clojure addresses the key concerns of OO: encapsulation, polymorphism, and inheritance.

This is a whirlwind tour, and we won't have time to cover the full details of all the Clojure code you will see. When we are done, I hope you will decide to explore for yourself. You can download and start using Clojure by following the instructions on the getting started page.

Just Enough Clojure Syntax

Clojure has <emph>vectors</emph>, which are accessed by integer indexes:

[1 2 3 4]
-> [1 2 3 4]

(get [:a :b :c :d :e] 2)
-> :c

In the preceding example, the initial [1 2 3 4] is input that you enter at the Read-Eval-Print Loop (REPL). The -> indicates the response from the REPL.

Clojure has <emph>maps</emph>, which are key/value collections:

{:fname "Stu", :lname "Halloway"}
-> {:fname "Stu", :lname "Halloway"}

<emph>Sets</emph> contain a set of values, and their literal form is preceded with a hash. Here is the set of English vowels, using backslash to introduce a character literal:

#{\a \e \i \o \u}
-> #{\a \e \i \o \u}

Lists are singly-linked lists, and are enclosed with parentheses. Lists are special: Not only are they data, they also act as the syntax for invoking functions. The list below invokes the plus (+) function:

(+ 1 2 3 4 5)
-> 15

Collections themselves act as functions. They take an argument which is the key/index to look up:

([:a :b :c :d :e] 2)
-> :c

({:name "Stu" :ext 101} :name)
-> "Stu"

Enough syntax, let's get started.

Encapsulation

Encapsulation is the hiding of implementation details so that clients of your code do not accidentally become dependent on them. In object-oriented languages, this is ususally done at the class level. A class has public methods, private implementation details, and various other scopes in between.

Clojure accomplishes the purposes of encapsulation in three ways: closures, namespaces, and immutability.

Closures

A closure closes over (remembers) the environment at the time it was created. For example, the function make-counter below closes over the initial value passed via init-val:

(defn make-counter [init-val] 
  (let [c (atom init-val)] #(swap! c inc)))

Let’s break this down:

defn defines a new function, named make-counter, that takes a single argument init-val.
The let binds the name c to a new atom.
The atom creates a threadsafe, deadlock-proof mutable reference to a value.
The octothorpe (#) prefix introduces an anonymous function
The call to swap! updates the value referenced by c by calling inc on it.
The value of the let is the value of its last expression. This let returns a function that increments a counter, which is then the return value of make-counter.

The atom c is private to the function returned by make-counter. The only public thing you can do is increment it by one:

(def c (make-counter))
-> #'user/c

(c)
-> 1

(c)
-> 2

(c)
-> 3

The counter example returned a single function, but nothing stops you from returning multiple functions. These multiple functions can then share private state. The new version of make-counter below returns two functions: one to increment the counter, and one to reset it.

(defn make-counter [init-val] 
  (let [c (atom init-val)] 
    {:next #(swap! c inc)
     :reset #(reset! c init-val)}))

This new make-counter returns a map whose :next value increments the counter, and whose :reset value resets it:

(def c (make-counter 10))
-> #'user/c

((c :next))
-> 11

((c :next))
-> 12

((c :reset))
-> 10

Why the double parentheses above? Two functions calls: The inner function call looks up the appropriate function, and the outer one calls it.

Closing over data is far more general than the simplistic model offered by private, protected, public, friend, et al. in OO languages. By combining multiple lets and multiple return values from a function, you can create arbitrary encapsulation strategies.

Similar encapsulation possibilities are available in any language that supports closures. Douglas Crockford describes a similar idiom in JavaScript.

Namespaces

A Clojure namespace groups a set of related data and functions. Inside a namespace, a Clojure var can refer to a function or to data, and can be public or private.

For example, Chris Houser’s error-kit library implements a condition/restart system for Clojure.

(with-handler
  (vec (map int-half [2 4 5 8]))
    (handle *number-error* [n]
      (continue-with 0)))

In the code above, with-handler, handle, and continue-with are public vars of the clojure.contrib.error-kit namespace. The int-half is a demo function that blows up on odd inputs. When a *number-error* occurs, the handler causes execution to continue with the value 0. (Note how this is more flexible than try/catch exception handling, which cannot recover back into the middle of some operation.)

Internally, error-kit keeps track of available handlers and continues using these private vars:

(defvar- *handler-stack* () 
  "Stack of bound handler symbols")
(defvar- *continues* {} 
  "Map of currently available continue forms")

The trailing minus sign on the end of defvar- marks the vars as private. These vars are implementation details, and are invisible to code outside the clojure.contrib.error-kit namespace.

Immutability

In OO languages, another purpose of encapsulation is to prevent object A from modifying or corrupting the private data used by object B.

In Clojure, this problem does not exist. Data structures are immutable. They cannot possibly be corrupted, or changed in any way, period. You can write query functions that return “private” state, without any fear of data corruption.

Polymorphism

For our purposes here, polymorphism is the ability to choose a different method implementation based on the type of the caller. So for example:

Flyer a = new Airplane();
Flyer b = new Bird();
a.fly();
b.fly();

a.fly() and b.fly() do different things because they are called on different concrete types.

Clojure provides a generalization of polymorphism called multimethods. A multimethod definition begins with defmulti, and then has a name, plus a dispatch function that is used to select the actual implementation: To mimic polymorphism, simply dispatch on the class of the argument:

(defmulti fly class)

Individual methods of a multimethod begin with defmethod, then the multimethod name, then the object that must match the dispatch function. Finally, you get the argument list in a vector, followed by the implementation of the method. For example:

(defmethod fly Bird [b] (flap-wings b))
(defmethod fly Airplane [a] (turn-propeller a))

Unlike polymorphism, multimethods do not limit you to dispatching on class. You can dispatch based on any arbitrary function of the method arguments. So for example, a bank account might have a :type entry that is used to determine the interest rate:

(defmulti interest :type)
(defmethod interest :checking [a] 0)
(defmethod interest :savings [a] 0.05M)

The :type attribute is a convention, but nothing prevents you from dispatching on a different attribute, or even dispatching on more than one at the same time! For example, the service-charge multimethod below dispatches on two different facets of the same object: the object’s account-level (::Basic or ::Premium) and its :tag: (::Checking or ::Savings)

(defmulti service-charge 
  (fn [acct] [(account-level acct) (:tag acct)]))
(defmethod service-charge [::Basic ::Checking]   [_] 25)
(defmethod service-charge [::Basic ::Savings]    [_] 10)
(defmethod service-charge [::Premium ::Checking] [_] 0)
(defmethod service-charge [::Premium ::Savings]  [_] 0)

The _ is a legal name, and is used idiomatically to indicate that an argument will be ignored. (There is no need to even look at the argument, since all the work has been done in choosing which method to dispatch to!) This example also demonstrates two other concepts:

The double-colon prefix resolves a keyword in a namespace. This prevents name collisions among keywords, just as object-oriented langauges use namespaces to prevent name collisions between type names.
account-level is a function (not shown here), not a simple key lookup. It returns ::Premium or ::Basic based on the the account type and the current balance. Thus an account can dynamically change its account level as its balance changes.

As you can see, multimethods are far more general than polymorphism. Instead of being limited to type-based dispatch, multimethods can dispatch on any arbitrary function of an argument list. This allows programming models that more closely resemble reality: after all, what real-world entities are limited to a single type hierarchy, and forbidden to change types over time?

Inheritance

In OO languages, inheritance allows you to create a derived type that reuses the behavior of a base type. For example:

class Person {
  String fullName() { /* impl details */ }
}
class Employee extends Person {
  AddressBookItem companyDirectoryEntry() { /* impl details */ }
}

This kind of reuse is so natural in Clojure that it doesn’t even have a name. For example, here is a function that returns the full name of a person, based on first and last names:

(defn full-name [p]
  (str (:first-name p) " " (:last-name p)))

Employees are like people, but have other properties and behaviors, such as a telephone extension. The company-directory-entry returns a vector of an employee's full name and telephone extension, like this:

(defn company-directory-entry [p]
  [(full-name p) (:extension p)])

Notice that company-directory-entry “reuses” the person-ness of its argument p by calling full-name on it. There is no special inheritance ceremony required to set this up, you just call functions when you need them.

You can pass either a person or an employee to full-name. For company-directory-entry, though, you must have an employee. Or, more accurately, you must have something that resembles an employee, to the extent of having a :first-name, :last-name, and :extension. This is an example of duck typing: if it walks like a duck and quacks like a duck, we assume it is a duck, without asking it to present its IDuck papers.

Many Functions, Few Types

The example above demonstrates another negative consequence of idiomatic OO style: the over-specification of data types. The return value of companyDirectoryEntry is given its own unique type, AddressBookItem. Each new data type like AddressBookItem requires its own life-support system: constructors, accessors, equals, hashCode, and so on.

In Clojure, an address book item would simply be a vector or a map. No new types, and no life support system required. Moreover, an address book item can be manipulated with any of the large arsenal of functions in Clojure's sequence library.

To see the problem with overspecifying types, consider this method from the Apache Commons:

// From Apache Commons Lang, http://commons.apache.org/lang/
public static int indexOfAny(String str, char[] searchChars) {
    if (isEmpty(str) || ArrayUtils.isEmpty(searchChars)) {
	return -1;
    }
    for (int i = 0; i < str.length(); i++) {
	char ch = str.charAt(i);
	for (int j = 0; j < searchChars.length; j++) {
	    if (searchChars[j] == ch) {
		return i;
	    }
	}
    }
    return -1;
}

The purpose of indexOfAny is to find the index of the first occurrence of one of the searchChars that appears in str. Note the unnecessary specificity of types: it works only with strings and character arrays.

Here's the Clojure version, using the sequence library's map, iterate, and for forms:

(defn indexed [coll] (map vector (iterate inc 0) coll))
(defn index-filter [pred coll]
  (when pred 
    (for [[idx elt] (indexed coll) :when (pred elt)] idx)))

Here is an example calling index-filter:

(index-filter #{\a \e \i \o \u} "Lts f cnsnts nd n vwel")
-> (20)

The expression above finds the index of the first vowel in the string "Lts f cnsnts nd n vwel", that is, 20. But index-filter is more general than the Commons version in several ways:

1. index-filter returns all the matches, not just one.

(index-filter #{\a \e \i \o \o} "The quick brown fox")
-> (2 6 12 17)

2. index-filter works with any sequence, not just a string of characters. For example, the call below works against a range of integers:

(index-filter #{2 3 5 7} (range 6))
-> (2 3 5)

3. index-filter works with any predicate, not just a test against a character array. In the example below, the predicate is an anonymous function that tests for strings longer than three characters:

(index-filter #(> (.length %) 3) ["The" "quick" "brown" "fox"])
-> (1 2)

That is a lot of extra power, especially given that the function is shorter, easier to write, and easier to read (given some Clojure experience, of course) than the Commons version.

Conclusion

Clojure solves the same problems that OO solves, but it solves them in different ways. Instead of encapsulation, polymorphism, and inheritance, you have closures, namespaces, pure functions, immutable data, and multimethods. Idiomatic OO gives you a bloated type system with duplicated code hidden away behind encapsulation boundaries and little hope for thread safety. Clojure offers a radical alternative: a lean type system, a rich function library, and language-level concurrency support that is usable by mere mortals.

There is a lot more to Clojure than we have covered here: lazy and infinite sequences, destructuring, macros, software transactional memory, agents, seamless Java interop, and more. But those are topics for another day.

[This article was originally published in the May 2009 issue of NFJS, the Magazine. I will be speaking about Clojure at several upcoming NFJS events, come join the fun.]

RunCodeRun now supports private builds

2009-08-04T17:26:00Z

We are pleased to announce that RunCodeRun is now accepting private builds. This means that you can now connect your private repositories on GitHub to RunCodeRun for your continuous integration needs. You can drop by our list of plans to see which best suits your situation.

We feel it important to note that RunCodeRun remains, as always, free for open source developers. If you are already an open source customer and want to upgrade, just sign in and head to the plans page and pick the option that works for you. You can keep all your open source projects active, now and forever, regardless of which plan you are on. And if you are just interested in getting started with an open source project? That’s easy: just sign up for an open source account. You can always upgrade later if you want to add private builds.

We look forward to seeing your projects clean and green!

Pairing and Conversations with Corey Haines

2009-08-04T12:28:00Z

Corey Haines was in our neck of the woods recently, and we were delighted to host him for three days of pairing and great conversations. We’re very fond of the craftsmanship model of software development, especially as a method of training. Although we haven’t gone about it as explicitly as Corey has in his journeyman tours, we all feel that we learned our skills largely through working with great programmers. (And if we had it to do over again, we’d seriously consider following Corey’s example and really being journeymen for a while.) Our interview process here involves a full day on-site, pair programming with members of our team, and we often learn cool things from even that amount of cross-pollination. So we felt especially fortunate having three days with Corey.

Corey arrived with an interest in Clojure, so he spent most of his time pairing with Stuart on one of our Clojure projects. And he stayed with Muness, in his apartment right upstairs from our office. The result? Two cool video interviews:

with Stuart discussing his Clojure book, and the way we do things at Relevance;
with Muness about Muness’ interest in the human side of software development: group dynamics, management, effective meetings, and retrospectives.

We couldn’t be happier with how these turned out. They highlight Stuart and Muness and their passions, but they show a lot about the rest of us here at Relevance as well. Thanks, Corey!

Relevance - Relevance Weblog

The Power of Names

Wrapping Assertions

Keeping the Domains Straight

Deeper Understanding

The Case for Clojure

Brian's Functional Brain, Take 1.5

Data Structures

Testing

JMX Integration

Source Code Organization

Parting Shots

Further Reading

NFJS, the Retro (Twin Cities Edition)

Setting the Stage

Gathering Information

Generating Insights

Deciding What To Do

Closing

Recommended Reading

10 Must-Have Rails Plugins and Gems (2009 Edition)

Quick and Easy Logging with LogBuddy

Installing and Adding LogBuddy to Your Project

Using LogBuddy

LogBuddy Initialization Options

Try It Out!

Easy Build Notifications with CapGun

Keep Models out of Your Views' Business! (Part 2)

Overriding Validation Error Messages

Which Messages Can I Override?

Interpolating values

Writing custom validations

Conclusion

Keep Models out of Your Views' Business!

Breaking the Link: The Obvious Ways

Breaking the Link: The Right Way

More To Come

RunCodeRun Basic Plan Now Available

Tarantula Supports Ruby 1.9

The Longevity of "Enterprise" Tools

Rifle-Oriented Programming with Clojure

Just Enough Clojure Syntax

Encapsulation

Closures

Namespaces

Immutability

Polymorphism

Inheritance

Many Functions, Few Types

Conclusion

RunCodeRun now supports private builds

Pairing and Conversations with Corey Haines