Gears Within Gears

A couple of days ago Ola Bini pulled my proposed ISpec mocking framework into Ioke (and did me the kindness of porting a change I made to Ioke/J into Ioke/C# – Number Infinity). It clocks it at around 300 lines of code (twice as many of test code) and I’m pretty pleased with the results, although several aspects of it could bear some refactoring.

Syntax

In its simplest form, it allows you to add simple mocks and stubs by method name:

For more BDD-friendly syntax, it’s expected that you use should receive syntax, which supports more advanced mock creation constructs:

The following method call count assertions are supported:

• never
• once
• twice
• atLeastOnce
• anyNumberOfTimes
• times(n)
• times(n..m)

Return arguments given as a sequence will be returned in the sequence they are given for each subsequent call to the mock:

The mocking support is still a work in progress. Significant omissions include friendly mock names, a more unified creation syntax, and more complex argument matchers (for example, Regex support: user should receive name(#/Guybr/)).

Design goals

I had basically two goals in mind for the syntax of mock creation:

• I wanted something that played nicely and looked good with ISpec, and in this respect I drew some familiar syntax constructs from RSpec mocking.
• I wanted a great deal of flexibility. In this I drew far more from Mocha than I did for RSpec, whose mocking framework I find continually limiting.

But in particular, I wanted to use the power of Ioke’s macros to allow me to specify complex mocks in a more concise way. In Mocha, being a Ruby library, you can specify your mocks as simple key-value pairs in a hash, but if you want to build a more complex mock you must break off into a new line and start constructing it using separate calls. Ioke allows me to chain multiple expectations implicitly against the same should receive call, and even to apply the same expectation to an entire group of them:

Next steps

I haven’t used the macro capabilities to their full power, and it shows in the code: much of it could reasonably be made much, much tighter through the use of macro syntax rather than simply leveraging the macro construct to manipulate conventional data structures. In particular the lack of that syntax manifests itself in a dismaying lack of consistency between different syntaxes for constructing mocks and stubs; unifying that is the number one thing I want to improve, structurally, in the framework.

But, most importantly, I haven’t yet used the framework in anger for anything; simply building it has consumed most of my Ioke hacking time. I suspect that it would benefit a great deal, as everything does, from real-world use; although I am an experienced tester with mocks, I am not yet an experienced user of my own. If you’re embarking on an Ioke project and need to test with mocks, please do let me know.

Tomorrow I’ll be hopping on a plane to Las Vegas for RailsConf ‘09, which comes at an interesting time for the community. The sagging economy, rise of alternative Ruby-like dynamic languages, and recent furor about sexism (about which I and many of my colleagues are pretty upset) make for a challenging set of obstacles for the technology that we all love. I’m curious about what the general mood will be, and I’m sure I’m not the only one.

I don’t know about other companies, but I know that ThoughtWorks has scaled back our involvement in RailsConf rather considerably this year, not because we don’t still like Rails but because sending people to Vegas in the middle of the week at the expense of billable or otherwise productive work is a luxury that all too few companies can afford these days. I’m glad I get to go and hope to repay our investment by blogging frequently about the sessions and sharing my thoughts on the goings-on. If there’s anything in particular you’d like to hear about, drop me a line at btguthrie@gmail.com and let me know. You can also follow me on Twitter.

In particular, if you’re interested in hacking on Ioke while you’re there please do let me know. I think it’s too late to suggest a BOFS session, but I may try to put something together anyway.

As for the recent controversy, my own feelings are perhaps best captured by Martin Fowler’s commentary, who reminds us yet again why we value his advice so much. Liz Keogh’s post is also fascinating. I could go on with more, but so many others have already said it better than I can; suffice it to say that I’m disappointed, and admire the creation but maintain my doubts about the creator.

In Ioke, a macro is a method that receives its arguments unevaluated. Instead of receiving a series of arguments, it receives a message. All code in Ioke is represented by message chains. A message looks something like this:

Take a look at that call to each. It receives two arguments, separated by a comma: the name of the variable to bind the incoming variable to, and the code for the loop. It’s equivalent to the following code in Ruby:

It’s pretty similar, except that in Ruby a block represents a special syntax form. In Ioke, calls to each follow the same syntax rules as any other kind of call, except that each is written as a macro, not a method. In the case above we don’t want to evaluate that first argument (name), because it doesn’t actually represent anything in the local scope. If you tried to evaluate it, you’d receive an error:

Macros allow a programmer to pick apart the arguments they receive and choose to evaluate them or not evaluate them, or evaluate them in particular contexts, as they so choose. They’re enormously powerful, but can be tricky to use, because without a structured argument list you’re never quite sure what you’re getting without taking a close look at the incoming message chain.

That’s where destructuring macros come in. dmacros are special kinds of meta-macros that allow you to write your code based on what you’re expecting from an incoming message. Here’s an example of a simple dmacro used by Message to allow you to turn transform any arbitrary code you give it into a message:

Think of them as a bit like multimethods: they perform the hard work of macro argument matching and allow you to write code that’s more clear and structured than it would otherwise be. Note that you still get access to the low-level call information that a regular macro would receive, so you can perform special tricks with the incoming arguments or the rest of the message chain if you’d like.

I’ve added an HTML formatter for Ioke’s testing framework, ISpec, and added TextMate bundle commands for test runners that use that formatter. I’ve shamelessly ripped off RSpec’s HTML formatter for a similar, though much less polished, style, and the results look something like this:

Because if you’re testing comprehensively, in my experience, you almost never need them. Unit and functional tests aren’t a panacea, but failures around incorrect types represent a miniscule proportion of the errors in the Ruby codebases I’ve worked on. You get them every once in a blue moon, but they are fixed easily and quickly, and everyone moves on with their lives. People still ask me sometimes if I miss static types, and my answer is always an unequivocal no. They eliminate a particular type of error that I almost never need to worry about.

Ola is also right that types aren’t the same as classes, and attempting to conflate the two will in all likelihood drive you towards class explosion and, ultimately, madness and penury.

That isn’t to say that interfaces shouldn’t have at least implicit contracts. In my own design, I try to follow the robustness principle whenever possible, and it improves code maintainability dramatically (nor does it does get discussed as a design principle nearly often enough). If it’s generally clear from reading the code what you can expect back from a method call and your types are suitably polymorphic then explicit type checks should be pretty rare.

The aim of software is, in a sense, to create an alternative reality. After all, when you use your cell phone, you simply want to push the fewest buttons possible and call, text, purchase, listen, download, e-mail, or browse. The power we all hold in our hands is shocking, yet it’s controlled by a few swipes of a finger. The drive to simplify the user’s contact with the machine has an inherent side effect of disguising the complexity of a given task. Over time, the users of any software are inured to the intricate nature of what they are doing. Also, as the software does more of the “thinking,” the user does less.

From My Manhattan Project: How I helped build the bomb that blew up Wall Street. Highly recommended; the article touches on the ethics of software development, user interface design, complexity, and the classic question of the degree to which a creator may be held responsible for the acts of his or her creation.

It is not Osinski’s fault that his software makes it very easy to perform some otherwise rather difficult algorithms; that is, after all, much of what a computer does. But it does make me wonder that he agreed to work on it understanding full well that the technique was built on entire mansions of cards, and it serves as an ample reminder that our moral compasses are so often attuned only to the values of those around us.

But what, then, is appropriate user design? Should business software be ugly, difficult to use? Should it, like a disassembled watch, expose its innards for all the world to poke and prod at? Must an operation that you suspect your user does not rightly understand always come with a warning label: “Don’t touch unless you really, truly know what you’re doing”? Isn’t that just condescending to your users?

Like everyone else, I’ve used my share of software that I absolutely loathed; software that made simple tasks hard and hard tasks devilishly impossible, their user experience an afterthought, a victim of shrinking budgets and small visions. If there’s anything I’d like to see improved in what you might term the ecosystem of enterprise software, it’s the fact that so much of it is, from a human point of view, really wretched. If you must make people use the stuff, don’t make them dread the experience.

But am I wrong? Should an ugly veneer serve as a reflection of inner ugliness, or of my own lack of understanding? I don’t know how many kinds of Photoshop filters work; should I as their user ask the designers of Photoshop for a poor interface design, so as to force me to pay a psychic penalty for my ignorance?

Of course not. As developers, our eagerness to please our clients and stakeholders is, after all, only human, and anyway, software projects do not have a great track record of success when it comes to satisfying the demands of their procurers. Some projects are wise and some are not; Osinki labored foolishly, although surely if he had not taken up the call some other equally talented developer would have. Agile development, I think, provides us with the tools to build software more rapidly and closer to spec than ever before; so let us then pick our projects wisely.

At ThoughtWorks, everyone submits a code sample as part of their interview process. The comment I received from my interviewer about mine struck me, though, and it sticks with me to this day. “The code looks fine,” he said, “but what’s with all the comments?”

My introductory CS course at Northeastern University taught me a lot of things that have resonated in my experience in the industry, but we were taught one thing that, as it turns out, almost none of my colleagues agree with: that all of your methods, classes, and modules should be preceded by a simple, one-line comment that states the purpose of code unit in question. Far be it from me to gainsay Neal Ford, who believes that code comments are a smell, but there are days when I disagree: Even developers with the best intentions and training in the world can’t always write clear code.

A Brief Re-Introduction to Class Re-opening

The problem manifests itself most acutely through the Ruby mechanism of class re-opening (sometimes dismissively referred to as “monkey-patching”). You can go about it in a number of ways, and the codebase I’m working on these days has employed each and every one of them at some point or another. The advantage you gain from being able to reopen classes is that you can patch the framework you’re using unobtrusively in order to fix bugs or improve performance. The downside is that you don’t get to choose the names of the methods you’re overriding: they may make perfect sense in the context of the class you’re overriding, but none whatsoever as an isolated patch.

A reopened class looks something like this:

In the first example, we’ve patched String directly; in the second, class_eval’d it for an added layer of complexity; and finally we’ve defined our own module and added it to String after the fact, which is fact the recommended way of going about it. We can use IRB and the method method to try to figure out where our patch is coming from:

Notice that only the last one gives us a helping hand when we’re trying to figure out where this method was defined.

Overriding, not extending

Now imagine there’s a bug in the String class: a colossally poorly-designed method, something that’s significantly impacting your ability to get something done in the language. (While this doesn’t happen in Ruby very often, it’s like to have occurred at least once in the framework of your choice.) In the bad old days, you’d have had to patch Ruby directly; if you were good about it, you’d submit your patch to Matz, and it’d get integrated as part of some future release. But the language itself gives you an escape valve: override the method, and your implementation gets used.

On my current project, we do this all the time.

But what happens when the framework gets upgraded? Is this extension still necessary? Why did anyone put it there in the first place? What’s with this Subversion check-in comment? Why didn’t anyone say anything in the code?

Enter alias_method_chain

alias_method_chain is a Rails method patched into Ruby that allows you to extend a method without blowing away the old version. You can read Marcel’s post on it on the Rails blog from back in the dawn of time, two years ago, when they added it to the framework. In action, it looks something like this:

Suddenly our extended method has an identity again: it has a name that clearly indicates both the method it’s trying to extend and the feature we’re adding on top of it. Hallelujah!

Why does this matter?

The ability to re-open classes is an insanely powerful tool. I love it, not least because it never means having to write another XUtil (XmlUtil, DateUtil, StringUtil…) class again to make up for the deficiencies of someone else’s API. I could never tell you, in good conscience, not to use it.

But cleaning up becomes a bit of a mess when you have to upgrade frameworks (or language versions, for that matter) as we’ve had to do recently on our project. We carry a copy of Rails around in our vendor directory, like most projects do, but we’ve tried to be good about making our extensions externally, through class re-opening, rather than patching the Rails code directly as men and women did in days of yore. But because, out of habit, none of these extensions carry any comments, we’ve had a devil of a time trying to figure out not what they do (we can always read the code) but why they’re there, and whether we can finally, for the love of God, delete them now that we’re upgrading to Rails 2.2.

But take it from me, one developer to another, who hath had to maintain thine extension, yea, even unto multiple new Rails versions: using the tips above will help me, and those like me, figure out what the dickens you were trying to do. And for Heaven’s sake, when you don’t have the luxury of naming your methods to make it clear what they do or why they’ve changed, leave a quick comment.

I gave a presentation on mocking and stubbing in Ruby a couple weeks ago at the Atlanta Ruby Group and the maintainers of the group have been kind enough to put the video online. It’s a large and energetic group and I had a lot of fun presenting, as indeed I always have watching others present there. If you’re new to unit testing in Ruby and you’re wondering what the fuss is about, check it out and let me know what you think at btguthrie@gmail.com. Slides here, or just watch the presentation.

Some highlights, or anyway things that caught my eye, when I read the 2009 Rails Hosting survey of Ruby on Rails developers:

• Around 60% of the community has been using Ruby and Ruby on Rails for 2 years or more. It’s not yet a mature community, but there is now a reasonably large body of expertise to draw from in solving problems in and around the framework.
• Rails developers on average develop two to five new applications per year, and deploy them several times a week to several times a week.
• Most of these are probably small:
  • Generally respondents either self-host or use a small-scale VPS service like Slicehost (which I myself host this blog on; recommended.)
  • Respondents claim to be highly sensitive to the price of their hosting provider.
  • Most don’t use performance, uptime, or process monitoring.
• It surprised me to see that almost a quarter don’t use any automated deploy process whatsoever, which sounds painful. Furthermore, 5% claimed they were still using FastCGI+Apache. Crazy.
• The community has largely moved over to Git as the SCM of choice, although Github is not widely used as a centralized code repository—only a third claim that their source code is hosted there.
• Passenger has, this year, finally surpassed Mongrel as the rails server of choice.

I see a community that’s still youthful but is starting to mature. I’m still proud to be a Ruby developer, and glad to be a part of the community. Here’s hoping for more good years ahead.

ResourceFull integrates with ActionController to provide a comprehensive RESTful resource modeling and querying framework. It provides parameter queryability, paging, sorting, separation of controller concerns, multiple formats (HTML, XML, JSON), CRUD access permissions, and API metadata surrounding the resource itself. It’s opinionated but is intended to provide you with as much as possible without limiting your ability to customize its behavior.

This plugin was extracted from a series of Rails projects intended to serve as the services tier of a series of loosely-coupled applications built in a style reminiscent of the RADAR architecture.

ResourceFull lives on Github at http://github.com/bguthrie/resource_full/.

GOALS

The major distinguishing features of ResourceFull are:

• Queryability: the ability to designate certain parameters as queryable, and map them to columns and SQL queries in the underlying model. These queries chain together multiple named or unnamed scopes and can be used either for a SQL SELECT or SELECT COUNT. This functionality may be moved into a separate plugin in the future.
• Pagination and orderability: it automatically responds to requests for limit, offset, order_by, and order_dir.
• Implementation: Default implementations for HTML, XML, and JSON controller requests.
• API documentation: ResourceFull-enabled Rails apps are able to provide automatic documentation of the resources they expose, up to a point. (This is enabled in large part by the queryability functionality and other resource-level descriptors.) It’s my hope that this can eventually be consumed by a Rails resource registrar that acts as the single source of record for multiple REST engines within an organization.

EXAMPLE

This allows for the following:

/users/bguthrie.xml
/users?name=Guthrie
/users?email_address=gmail
/users.xml?city=Chicago&name=Brian,Paul,Alicia&order_by=city&order_dir=asc
/users.xml?limit=10&offset=30
/users/bguthrie/addresses

>> UsersController.to_xml
=> "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n\n  ..."

API DOCUMENTATION

To enable ResourceFull to document your resources at /resources.xml and /resources//routes.xml, add map.api to your routes.rb file.