DABlog

I’ve always vaguely disliked horse races. The anthropomorphizing of the horses, the claims that they know that they’re involved in a race and that they share the goals of their owners, is manifestly silly and self-serving. And the whipping always bothered me. I suppose I made myself believe that horses didn’t really care and that an attack with a whip was, to them, kind of like a verbal exhortation to us. (Not that verbal exhortations can’t be painful, but they’re not physical).

The death of Eight Belles shocked me out of my indifferent, complacent position.

All the crap in the news about how noble she was, how competitive her spirit, how great her self-sacrifice… it’s all smug and disgusting beyond belief, despite the accompanying descriptions of the tears glistening in the eyes of the various stakeholders. What really happened was that this horse was forced to run as fast as she could, for reasons she could not understand and that had nothing to do with her well-being, and as a direct result, her legs fell apart, and then someone killed her.

That’s it; that’s all there is to it.

Why is this allowed to go on? Is it simply because more horses survive races than don’t?

For some reason, we continue to give the benefit of the doubt to this bizarre, nasty, money-drenched “sport”. Except that for me, at this point, there is no doubt, and no further conferral of the benefit.

In part 1 of this two-part post, I explained my concern that the word “resource” has become too closely associated in Rails-related usage with some combination of model, database table, and controller/model stack—none of which do justice, as definitions or even first approximations, to the concept of a REST resource as originally described by Roy Fielding. Here, I’m going to expand on this observation by exploring a few ramifications of the same topic.

Resources, controllers, and models (or lack thereof)

As I explained in the previous post, the concept of “resource” has no database implications—indeed, no implementation implications. A resource does not have to have a corresponding model. It also does not have to have a corresponding controller. Resources are far more high-level than controllers and models. Controllers and models are tools with which you provide access to representations of resources.

However, if you want to draw a line between resources and Rails, by far the better line to draw is the one that points to controllers rather than models. A controller is not a resource, but it comes closer than anything else in your application to taking on the features of your resources. Models are another big step away.

If controllers are closest to resources, how does this play out? One way is in the creation of resources for which requests are handled by a controller that has no corresponding model.

My favorite example of a likely modelless resource is the shopping cart. In Ruby for Rails, I use a shopping cart in my central example. When I started working on this application, I tried to model it directly; I imagined I would have a ShoppingCart class, a shopping_carts table, and so forth.

I quickly realized, however, that I didn’t need that. What I was calling a “shopping cart” was really a virtual construct or, in Rails terms, a view. I had Order objects and Customer objects, and the shopping cart was basically a screen showing all of a particular customer’s open orders. Calling it a “shopping cart” was just a kind of semantic sugar. There was no need to persist it separately from the persistence of the orders and the customer.

If I were writing the same application today using RESTful idioms, I would in all likelihood do:

map.resources :customers do |c|
  c.resource :shopping_cart
end

or words to that effect. I would then have a shopping_carts controller, with a show action (probably leaving all the related CRUD stuff back in the orders controller, though there might be several ways to approach that part of it). And I would, without hesitation, describe the shopping cart as a resource—even though it has no ShoppingCart model behind it. From the perspective of the consumers of my resources, it doesn’t matter whether there’s a ShoppingCart model (and shopping_carts database table) or not. I can decide on the best application design, and use RESTful Rails techniques to support my design decisions appropriately.

A resource is not a model, and it’s also not a controller. Identifying the resource with the controller is, however, somewhat closer to the mark. The controller layer conforms most closely to the resource mapping, which makes sense since the controller is the port of call when someone connects to your application.

Another area where misunderstandings arise in the course of designing RESTful services in Rails is in the matter of how identifiers (URI) map to resources—and not just how, but how many.

Identifiers and resources: not always one-to-one

I’ve seen people tie themselves in knots trying to come up with the best way to label and/or nest resources. One of the principles that’s gotten lost in the mix is that the ratio between resources and identifiers does not have to be one-to-one. Fielding states:

[A] resource can have many identifiers. In other words, there may exist two or more different URI that have equivalent semantics when used to access a server. It is also possible to have two URI that result in the same mechanism being used upon access to the server, and yet those URI identify two different resources because they don’t mean the same thing.

Therefore, it’s possible that this:

http://dabsite.com

and this:

http://dabsite.com/welcome

can identify the same resource, which would probably be described as something like “The welcome and orientation information at dabsite.com”. The reason they’re the same resource is not that they generate the same HTML. Rather, they’re the same resource because they’re published as the same resource.

It’s also possible that this:

http://dabsite.com/orders/211   # 211th order in the system

and this:

http://dabsite.com/orders/042208-003  # third order placed on 4/22/08

identify different resources, even if the third order placed on 4/22/08 happens to be the 211th order in the system. That’s because resources are not database rows. In this case, the two requests might generate the same HTML, but still pertain to different resources.

You don’t have to make a point of having a non-one-to-one ratio between your resources and your identifiers. Just be aware that if such a ratio emerges, in either direction, you’re not doing anything inherently “unRESTful.”

CRUD and REST and resources

One of the nice things about the REST support in Rails is that it dovetails with CRUD-based thinking about modeling. I add in haste: REST is not CRUD, and CRUD is not REST. (That’s no secret, but I want to go on record with it.) But in Rails, there’s a nice relationship between them.

The REST support in Rails emphasizes the convention of CRUD operations. map.resources gives you a fistful of named routes that have built-in knowledge of CRUD action names. The emphasis on CRUD at this level encourages you to think of modeling for CRUD. Instead of having, say, a users controller with a borrow_book action, you can have a loans controller with a create action. In many cases, this way of thinking might also wag the dog of your domain modeling. Thinking about CRUD in the controller might, for example, lead you to conclude that you should have a Loan model.

It’s perfectly fine—indeed, in my view, it’s very productive—to think along these lines, to bring your modeling and your REST-friendly CRUD operations into harmony, as long as you understand that none of this is actually about resources as such. Rather, it’s about the Rails flavor of implementing the handlers that underpin the creation of resource representations.

Does that sound like just a lot of extra words? It isn’t. It’s a lot of words, but they’re not extra. Again, it’s important not to squeeze the entire framework into the “resource” label. Let a resource be a resource, and let the handler layers be handler layers. They’re nicely engineered—but they’re not resources.

And then there’s the word “representation,” which crept into my “extra words” sentence but which is the least extra of all of them.

Representations: the one that got away

The representation is, in my view, the one that got away: the central concept in REST that no one in the Rails world ever seems to talk about. We need to, though. It’s vitally important.

Your server does not traffic in resources. It traffics in representations of resources. Users of your application do not receive resources. They receive representations. The distinction is big; at stake is the entire meaning, and meaningfulness, of the notion of a resource.

We need the concept of “representation” because it’s the part of REST theory that relieves the pressure on the term “resource.” After all, how can a resource be a “conceptual mapping” (Fielding) and a sequence of bytes that a server sends you and a controller-model stack…? It can’t, and it’s only the first of these things. The second, the response itself, delivers a representation of a resource.

One resource can have many representations. There’s no big news here; we all know that a server can give us a text version of Jane Eyre or a movie version or an audio version. (I’ll refrain from getting philosophical about whether or not a book and a movie are “the same” in any deep sense. They’re the same enough, in this context.) The point is that we don’t need to mush everything into the term “resource.” Rather, we benefit by yanking that term up to the high level where it belongs, and applying the term “representation” to the actual response we’re getting.

Fielding has much more on representations in his dissertation, and I’m not going to try to paraphrase it here. My point is to encourage the liberal use of the term in Rails discourse about REST. The poor term “resource” has already been given too much to do. We need to delegate some of the domain description to the other terms that apply to it.

Now what?

The use of the term “resource” to mean things that, I’ve argued here, it really doesn’t mean is rather deeply entrenched, and widespread, in Rails discourse. I don’t have any quick fix for this. I do have a few recommendations, though.

First, read Roy Fielding’s dissertation. You can skip to chapters 5 and 6 and get a great deal out of them.

Second, pay particular attention to the concept of the representation. I don’t think we can get much further in exploring REST and Rails unless the representation makes a comeback. “Resource” is just plain spread too thin in the way it’s used in and around Rails, and there’s no reason why it has to be, if we look at the theory as a whole.

Third, and last, don’t assume that any deviation from the out-of-the-box behaviors in your RESTful Rails applications is unRESTful. The defaults are in place because they’re high percentage. But they’re just as opinionated as the rest of Rails, and in some respects more so. That’s OK, but do understand that they’re REST-friendly tools. They’re not a definitive statement on the entirety of what REST is.

REST is not an easy topic, and it’s unlikely that anyone is going to create a way for you to create and maintain RESTful applications, over time, without you trying to get a handle on it and developing your own understanding of resources, representations, requests, and responses. I hope these posts will help you out in that endeavor.

References

Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures.. Doctoral dissertation, University of California, Irvine, 2000.

Chad Fowler wrote an interesting article this week on the subject of Great Ruby Code. The article concludes with an invitation for comment:

Anyway, I still don’t have a satisfactory list of great Ruby code. I’d like to build such a list. So, please leave a comment saying the name of an open source Ruby project you feel represents truly great Ruby code.

My comments are somewhat “meta”, and I had an interesting chat with Chad about the whole topic of greatness in Ruby code after I’d read the article, so I thought I’d make my comments here in an article of my own.

For me, the very concept of great Ruby code contains the seeds of its own destruction. Here’s why.

When I see Ruby code and think, “This is great,” what I usually mean, at least as a first approximation, is that Ruby is great. I don’t mean that everything written in Ruby is automatically great. But I do find that a lot of what’s involved in writing what I consider beautiful Ruby code is getting out of Ruby’s way. Ruby is famous for getting out of your way; but you can and should return the favor.

I’m slipping between “great” and “beautiful,” which isn’t fair but maybe that’s part of the problem: I’m not sure what pure greatness in Ruby code would be, because I tend to perceive Ruby code in terms of beauty—not down to the millihelen,[1] perhaps, but as an overall matter—rather than greatness; and I can’t really give an individual programmer “credit,” so to speak, for the beauty I find in, say, yield or class << object or the technically unnecessary but, in my view, manifestly elegant class/module distinction.

Then there’s the subjectivity issue (as many of you non-fans of class << object are probably thinking right about now!). Of course Chad isn’t anticipating universal agreement on what’s great in Ruby code. But for me, the impossibility of consensus is another seed of the very concept’s own destruction. It’s an irony, even a paradox: if there is such a thing as greatness in Ruby code, we’ll never find it because once we shift the discussion to the plane of “What do you consider great?”, it’s likely to unravel in the same way that discussions about what’s great in any art unravel.

And about that art thing: Coding is of course an art, but it’s a peculiar one in that the artist is operating within the boundaries set by another artist&mash;namely, the designer of the language. (Note that I said coding, not programming. I’m not trying to drive a wedge between them, but as Knuth and others have shown us, there are aspects to the art of computer programming that are not about this or that language, and I’d like to keep the terminology at least a bit separate.) Is it like music? Are we interpreting Matz’s score? Or is Matz the playwright, we the actors? Or perhaps Matz is like whoever invented baseball: a set of rules within which we elect to operate. Well, there are great baseball players….

Maybe greatness in Ruby is ours to lose: If you follow stylistic best practices (which is another, but in my view related, matter), and above all let the language talk to you and don’t “write {Java,C,Perl,...} in Ruby,” your code will be great, or beautiful if you prefer, because you’ve collaborated successfully with Ruby. And yes, I do think that Ruby confers an advantage here over many other languages. For me, the most important key to Ruby’s beauty and its greatness is that Ruby code gets clearer, rather than more cryptic, as it gets shorter. I don’t want to jump through the hoop of reciting all the obvious facts (that this can be true in other languages; that Ruby code can be cryptic; etc.). I present it for what it is: my take on the magic of Ruby. I’ve always said that as you work on a Ruby program, code disappears from your screen. So it does—and the program becomes more, rather than less, expressive and communicative.

There’s no tidy stopping point to this exploration, and that’s as it should be. I encourage you to go to Chad’s article and read it and respond. I don’t expect us to end up with a definitive list of great Ruby code. But what Chad is doing is inviting us to look—really look—and I find it well worth the trouble.

[1] A millihelen is the amount of beauty required to launch one ship. (I wish I could take credit for that one but I only know it as an old joke.)

There was a response to my post from yesterday on Procnew.com, which pointed out that when you’ve got this:

x ||= y

it doesn’t expand to this:

x or x = y

(which is what I said in my last post) but rather to this:

x || x = y

I believe that’s right. It’s kind of hidden until you do:

a = x ||= y

and you start to see that it behaves like the || expansion, not the or expansion.

The example on Procnew.com has one glitch, which is that on line 9 of the irb session, it’s using a value that’s already set (h[:y]), so it’s never going to jump over the || anyway. Still, I believe the point is right.

Pending other edge-case edge-cases, anyway…. :-)

In Ruby, you can conditionally set a variable like this:

  x ||= 1

If x is not initialized—or if it is set to nil or false—it will be assigned 1. If it’s already set to a Booleanly true value (i.e., anything other than nil or false), it will remain unchanged.

Most descriptions of this idiom, including mine, have said that it expands to this:

  x = x || 1

Last year, though, an edge case came to light on the ruby-talk mailing list. It involves hashes with default values.

Trouble in ||=-land

Here’s an irb session illustrating the case. First, we’ll create a hash with a default value of 1.

  >> h = Hash.new(1)
  => {}

Remember that the default value is what the hash returns for non-existent keys. There are no assignment implications; referring to a non-existent key does not result in setting that key in the hash.

  >> h[:x]
  => 1
  >> h
  => {}        # still empty!

Now let’s try the ||= idiom.

  >> h[:x] ||= 2
  => 1

Once again, no assignment has taken place:

  >> h
  => {}

This struck a number of us on the mailing list as weird. It certainly means that ||= does not expand the way we had assumed it did. Here’s the proof: try the expanded version, and you’ll see that it does assign to the hash, as you’d expect.

  >> h[:x] = h[:x] || 2
  => 1
  >> h
  => {:x=>1}

So there we have proof that x ||= y and x = x || y are not interchangeable.

That raises two questions: first, what does x ||= y expand to, and second, do we like it?

The true expansion of ||=

At RubyConf 2007, I was running a “Ruby Clinic”, where people could come and go and ask questions about Ruby. Matz stopped by for a while, and the ||= topic came up. He explained that the real expansion is:

  x or x = y

Note (a day later): It’s been pointed out to me that expansion as x || x = y is more accurate. I believe that’s right, though my examples here didn’t flush it out.

Sure enough, expanding it this way produces parallel results in the hash case. Continuing the same irb session:

  >> h
  => {:x=>1}
  >> h[:y] ||= 3
  => 1

After that conditional assignment, the hash has not changed.

  >> h
  => {:x=>1}

And expanding it in the “or” style also does not change the hash:

See “Note”, above.

  >> h[:y] or h[:y] = 3
  => 1
  >> h
  => {:x=>1}

That clears that up. But do we like the way this plays out with hash defaults?

Editorial comments

I have mixed feelings about it. I can see that it makes sense. On the other hand, I can’t help thinking that when you write this:

  hash[:x] ||= 2

you’re really expecting the hash to end up with an :x key. In other words, my gut feeling is that it should mean:

  hash[:x] = 2 unless hash.has_key?(:x)

However, I understand that having it mean that would involve special-casing the hash case, and in the long run, I’m not in favor of that.

So what it comes down to is: heads up a bit with ||=. It works fine, but you need to know the real expansion.

I’ve commented on the main Rails mailing list and elsewhere about some concerns I have about the way the term “resource” has been adopted into Rails practice and discussions. I’d like to explain those concerns in a little more detail.

In this post, I’ll talk about the definition of a resource and why it’s a good idea not to overpaint the original definition with a redefinition based on the specifics of Rails. In the next, follow-up post, I’ll comment on several closely related issues, including the usefulness of model-less resources, why it’s better (though not perfect) to identify a controller with a resource than to identify a model with a resource, the relation between CRUD and resources, and the role of the “representation”—an important and concept often overlooked in discussions of REST in Rails.

Controller + model: what a resource isn’t

The problem, in a nutshell, is that the term “resource” has come to be understood widely as meaning “ActiveRecord model” or, perhaps more commonly, “controller-model stack.” People say that they’ve “created an item resource” when what they mean is that they’ve generated a item model and an items controller. There’s no reason for there not to be a short, concise term for “name-matched controller-model stack.” But that word should not be “resource.”

Equating “resource” with controller-model stack has the unfortunate effect of leaving us without a term to refer to what Roy Fielding originally meant by “resource”—which is definitely not “controller-model stack” or anything like it. (More on what a resource is presently.) Fielding’s description of a resource is deeply interesting, and worth protecting from terminological drift. Moreover, there’s no loss involved. In fact, by teasing apart the threads of what’s a resource and what isn’t, we can actually get more out of the RESTful tools available in Rails.

Defining “resource” as controller + model severely limits imaginative thought about how a resource, in the original sense, might play out in Rails. By imaginative, I do not mean improvisatory or chaotic. The Rails REST conventions are very powerful and tremendously useful, and I’m fine with being conservative about deviating from them ad hoc. But I wince when I see people agonizing because they’ve manipulated Model A in Controller B, and think that they’ve violated RESTful principles because they’re crossing resource lines. That’s not how it works; that’s not how the concept of resource maps to Rails technology.

Obviously Rails uses controllers and models, so whatever a resource is, somewhere along the line it’s likely to involve those things in a Rails application. The wrong turn, though, is in assuming that a resource is a controller and/or model.

I tend to think that much of this way of viewing the matter comes from the so-called resource scaffolding. It’s easy to understand why Rails developers, presented with a tool that generates a controller-model chain and calls it a “resource,” would either not see the need to question the terminology, or would be reluctant to do so. But there is a need to question it. The term “resource,” as used very commonly in Rails discussions, bears much more resemblance to how it’s used in the context of Rails scaffolding than how it’s used by Fielding. That doesn’t benefit anyone.

Scaffolding or not, something has led people to think that a resource consists of a controller and a matching model. It doesn’t.

What a resource is

Rails is database-intensive, so the temptation exists to conclude that the word “resource” has something to do with database tables and persistence. Fielding could hardly state the case against this perspective more strongly:

The resource is not the storage object. The resource is not a mechanism that the server uses to handle the storage object.

Already one has to wonder how the generation of an ActiveRecord model and migration ever came to be viewed as part of creating a resource per se (as it is in the scaffolding). Anyway—Fielding goes on to define what a resource is:

The resource is a conceptual mapping — the server receives the identifier (which identifies the mapping) and applies it to its current mapping implementation (usually a combination of collection-specific deep tree traversal and/or hash tables) to find the currently responsible handler implementation and the handler implementation then selects the appropriate action+response based on the request content.

This sentence is a bit more complex than the first two, and it’s worth breaking it down for the sake of seeing how it might map to Rails.

The key idea is that a resource is a conceptual mapping. You send a resource identifier to a server. The server sends back a response (a “representation” of the resource, as we learn elsewhere). In between, the server does what it has to in order to generate the response.

The response is a representation, not a resource. And the mechanisms by which the representation is generated are not, themselves, the resource. In Rails, those mechanisms typically include the routing system (which I would roughly identify with what Fielding calls “the current mapping implementation”) and the controller objects with their actions (the “responsible handler implementation”). Again, these mechanisms are not the resource. And the model layer, which lies yet further away in the architecture, is really not the resource.

The benefit of splitting hairs over the terminology is that it points the way to recovering Fielding’s original concept of a resource, of which I don’t get very many glimpses in the typical discussion of RESTful support in Rails. To the extent that you are setting up models and controllers and RESTful routing, you are putting in place the wiring that will allow your system to fulfill its contract as a provider of representations of certain resources. To the extent that you are determining what resources your system is responsible for, you’re performing a task that has no dependency on Rails or any other specific software tools.

The robustness of resources

Part of the problem with using “resource” to refer directly to parts of the Rails application itself is that it introduces a fragility into the concept of resource, and the identity of specific resources, that really shouldn’t be there. If you declare that your system is responsible for the Resource N, then it shouldn’t matter how many controllers, actions, models, and database tables you use. I don’t mean that it doesn’t matter in terms of software design. I mean that Resource N should be above the fray. It should be robust enough not to depend for its identity as a resource on the specifics of the way you handle the mapping of identifiers to representations.

It’s instructive in this context to consider how the concept of “resource” plays out when you’re serving a static HTML page. The way it plays out is the same as the way it plays out when you’re generating a dynamic response. In other words, whether or not something is a resource has nothing to do with the question of whether or not its representations are generated dynamically, nor with the question of whether a database has been queried or a template rendered in the process of the production of a representation.

This is just terminological common sense. Imagine if you were publishing information about resources available through your system, and you had to explain that sometimes they weren’t really “resources” because they didn’t hit a Rails controller and database table. That would be ludicrous. Obviously a resource is a resource, not because of how its representation is generated behind the scenes but because a representation is returned, however it’s generated, based on a mapping of identifiers to request handlers.

So if you start thinking of controllers and models as actually being resources, you’ve painted yourself into a corner where you have no term that describes a resource in a higher-level sense—no way to identify the “conceptual mapping” that Fielding stipulates. Controllers and models are part of the handling and response mechanism. They are not resources.

But once you decouple the notion of resource from the specifics of how Rails applications generate representations of resources, a lot of other things fall into place. In the second half of this essay, I’ll be looking at several REST-related topics that I think benefit directly from the liberating and sense-making effect of observing the distinctions among resource, representation, and handler mechanisms.

References

Fielding, Roy Thomas. Architectural Styles and the Design of Network-based Software Architectures. Doctoral dissertation, University of California, Irvine, 2000

Long time, no blog. But now I'm out of hibernation.

I've got some Rails training courses coming up, including:

• Advancing with Rails, April 14-17, New York City
• Intro to Rails, June 9-12, Berlin, Germany
• Advancing with Rails, June 16-19, Berlin, Germany
• Intro to Rails, June 24-27, London (at Skills Matter)

See Ruby Power and Light for details.

The Berlin courses are being taught in English. The info about them on the Web might only be in German... but you can always contact me for more info if you're interested. Berlin is a very cool place -- I highly recommend it!

I suspect it won’t appeal to the Thanksgiving-inclined, but I’ll be teaching my “Advancing With Rails” course, for intermediate Rails developers, in Berlin, Germany, November 19-22.

Advancing With Rails is designed for people who have done some Rails… read a couple of books… and want to keep going and get better at it. I’ll be covering Ruby language topics as well as Rails techniques and best practices.

The course will be conducted in English, though I speak German and can field questions in either language.

More info here.

My Ruby/Rails consultancy, Ruby Power and Light, LLC, is offering two Ruby on Rails training courses this Fall, both hosted by Exceed Education in Edison, New Jersey:

• Introduction to Ruby on Rails, October 23-26
• Advancing With Rails, November 6-9

I will be the instructor for both.

You can get more information on the courses, and on signing up, at Ruby Power and Light—just follow the links in the banner box.

I love reading Wikipedia, and I’ve learned a lot from doing so. I’m not, in other words, rabidly anti-Wikipedia. But I do have a few serious concerns about it.

It seems to me that Wikipedia is, in effect whether or not in intent, pushing the Web in exactly the direction it isn’t best suited for: namely, centralization of information. Mailing list posts and IRC channels are full of links to Wikipedia articles, on everything from… well, on lots of things. It seems that the standard way of saying, “If you’re not familiar with the term I just used, here’s how to learn about it” is to provide a Wikipedia link.

I strongly suspect that this is automatic on the part of the people doing it—automatic, that is, rather than based on a thorough search of all the resources available on a given topic and a reasoned decision about which is best-written and/or most informative. That’s the thing: Wikipedia provides something close to one-stop shopping. You’ll find something on almost anything.

Furthermore, Wikipedia itself seems to buy into and cultivate the image of itself as a centralized, objective source of information about everything. One symptom of this is the fact that links within Wikipedia articles are always, or very nearly always, links to other Wikipedia articles. In spite of how open it is, in terms of contributions, it’s ultimately a closed system.

Yes, external sources are indicated at the bottom of articles. But the providing of sources, while important in terms of academic honesty and paper-trailing, never stopped scholarly publications from taking something very close to a “voice of God” position with regard to their subject matter. And it doesn’t stop Wikipedia from doing the same thing. How often have you bothered to go look up all the books and articles listed at the bottom of a Wikipedia article, and carefully analyzed how the information was gleaned and pieced together?

The editorial emphasis on balance and completeness and objectivity is another troubling sign. What’s wrong with balance? What’s wrong with it is that it’s a mirage. Any undergraduate who’s taken a reasonably decent mass communication course knows that what the news media call “balance” is simply an editorial or presentational style. And it requires constant reinforcement. “We report; you decide,” says Fox. “We’ll give you the world,” says at least one radio station (or conglomerate, probably, at this point). The idea is that the discouse provides a perfect substitute for the reality, so you can consider yourself to have been served the reality when you consume the discourse.

Wikipedia operates, I believe, in exponentially greater faith than the news media. But the philosophy of representation is the same, and it’s very old-school. An article is a simulacrum of a discrete, finite reality, and an article’s suitability for publication can be measured by how closely it has cloned that reality. While there’s often room for improvement, every article has the noble goal of achieving a perfect fit with its subject matter, and the potential to do so.

The fact, however, is that it’s not in the nature of written discourse to be a perfect fit with some arbitrary slice of reality. It doesn’t work that way. There’s no shame in acknowledging this, but Wikipedia battles against it.

What troubles me is not just that it’s child’s play to debunk the “voice of God” philosophy of discourse, but that I’d thought the Web was doing a pretty good job teaching people that reality and discourse actually map to each other sloppily, crazily, contradictorily, and ironically. Measured both by its editorial policies and by its wide, eager adoption as a centralized authority, Wikipedia unfortunately pushes against this more intriguing and, I would argue, more balanced take on things.

In Ruby, you can write methods whose names end in ! (exclamation point or “bang”). There’s a lot of confusion surrounding the matter of when, and why, you would want to do so.

What ! does (and does not) mean

The ! in method names that end with ! means, “This method is dangerous”—or, more precisely, this method is the “dangerous” version of an otherwise equivalent method, with the same name minus the !. “Danger” is relative; the ! doesn’t mean anything at all unless the method name it’s in corresponds to a similar but bang-less method name.

So, for example, gsub! is the dangerous version of gsub. exit! is the dangerous version of exit. flatten! is the dangerous version of flatten. And so forth.

The ! does not mean “This method changes its receiver.” A lot of “dangerous” methods do change their receivers. But some don’t. I repeat: ! does not mean that the method changes its receiver.

Don’t overuse the !

Not every !-method changes its receiver, and not every receiver-changing method ends with !. There’s Array#pop/push/shift/unshift/concat/clear, and lots of others.

Don’t add ! to your destructive (receiver-changing) methods’ names, unless you consider the changing to be “dangerous” and you have a “non-dangerous” equivalent method without the !. If some arbitrary subset of destructive methods end with !, then the whole point of ! gets distorted and diluted, and ! ceases to convey any information whatsoever.

If you want to write a destructive method and you don’t think the name conveys destruction, you might be tempted to add a ! to make it clear. That’s not a good idea. If the name of a destructive method, without a !, does not connote destruction, then the name is wrong and cannot be repaired by slapping a ! on it.

In such a case, you should create the traditional pair of methods: a non-bang method and a bang method. It’s conventional to define the non-bang method in terms of the bang one. Here’s an example involving a simplistic version of an Array#flatten_once method (it doesn’t handle nested objects other than arrays very well, but it makes the bang-point):

  class Array
    def flatten_once!
      res = []
      each do |e|
        [*e].each {|f| res << f }
      end
      replace(res)
    end

    def flatten_once
      dup.flatten_once!
    end
  end
 

The non-bang method is defined in terms of the bang method. You wouldn’t want to write an isolated method called flatten_once! without the matching non-bang version, since there’s no way to measure the “danger” except in relation to the non-dangerous method.

[Aug. 16, comment in response to IRC question from apeiros: you can also define the bang method in terms of the non-bang method, but in the Ruby source code it’s usually done in the direction I’ve done it, and I’ve followed that practice here.]

Danger takes many forms

Sometimes you get more than one kind of “danger” even within one bang method. Take String#gsub!. This method changes its receiver:

  str = "David" 
  str.gsub!(/$/, " Black")
  str                        # David Black
  

It also differs from gsub (non-bang) in that if the string does not change, gsub returns a copy of the unchanged string but gsub! returns nil:

  str.gsub(/xyz/, "blah")    # David Black
  str.gsub!(/xyz/, "blah")   # nil
  str                        # David Black
  

The ! in gsub! gives you a heads-up: it warns you of danger, and that means that before you use the method, you should find out exactly how it behaves. (A simple “ri String#gsub!” should do it.)

Forget “intuitive”

It may not be easy or, to use a heavily overworked term, “intuitive” to think of ! as meaning “dangerous”, or to craft your method names so that the !’s make sense in that context. It’s worth it, though. Give Ruby (and Matz) the benefit of the doubt. This use of ! probably does not occur in other languages you’ve used. But it works really well. If you let go out of the notion that ! means destructive, and if you think through the naming and pairing of dangerous and non-dangerous methods, you’ll see how valuable a flag the ! can be.

As of this morning, I can't find my London cell phone. Yes I know it sounds pretentious for an American even to have one... but I go to London usually two or three times a year, and you really can't have any kind of social life over there without one. Anyway, I'm at home in the U.S., and I can't find the phone.

That means I will almost certainly have to buy another one, solely because I'm too stupid to have put it away properly last time I got back from London.

I consider the price of the new phone to be a Stupidity Tax payment. I pay several hundred dollars a year in Stupidity Tax. I forget to cancel hotels; I neglect to send in rebate forms; I lose things. I have to say, the losing things thing is very deep-rooted; there's more to that syndrome than stupidity. Still, to the extent that I lose expensive things that should be simple to keep track of, their replacement is Stupidity Tax.

Thinking of all of this as Stupidity Tax actually makes it a little easier to deal with. It's just part of the cost of living. Of course I'd like to reduce it as much as possible. But it's unlikely I'll ever reduce it to zero. Life is too much of a sieve to hope for that. At least I can keep things interesting by rotating the reasons for the tax: a lost item here, a forgotten bill there. I'd like it not to get too interesting... but the Stupidity Tax is here to stay, so I might as well try to adapt to it.

I’m in Boston, having just spent four days at the Boston Early Music Festival. My brother Gavin, director of the Princeton Early Keyboard Center, rented an exhibitor’s room—basically a hotel room from which the beds have been removed—where he displayed his oldest harpsichords (one made in London in 1785, one made in Italy in the late 17th century). Visitors to the room were encouraged to play on the instruments, and many did.

It wasn’t just a display, though. Gavin also produced something like fifteen half-hour musical recitals, involving himself, me, and various musical colleagues and friends. The result was that Room 921 at the Radisson was a hot-spot of wonderful performances and presentations. Highlights included:

• Baroque music performed by its composer, Grant Colburn (unusual at an early music event!)
• John Thompson performing on the qin (pronounced ‘chin’), a Chinese instrument, with Gavin playing clavichord selections to complement the pieces
• John Burkhalter discussing the Neff manuscript, a one-of-a-kind handwritten collection of pieces, dating from late 18th century Pennsylvania and belonging to John
• Two recitals by the baroque group Col Legno, of which I am a member

And there was more. Room 921 was, as Gavin and I said to each other almost simultaneously when we were discussing it afterwards, a festival within a festival. Congratulations to Gavin for producing these four days of music, and thanks to everyone who participated and everyone who came to hear us.

I also spent a lot of time looking at the exhibit halls, where there were lots of instrument makers and sheet music sellers. There were not as many cellos as I would have liked; in fact, I only saw three. Viols seem to rule at this event, and the violin family is mainly represented by the smaller instruments. I guess it’s understandable, since the makers have to lug the instruments to the festival… but I still would have liked to have seem more baroque cellos. There were a lot of bowmakers on hand, though, and that was interesting.

I don’t think you have to be a language snob to wince (and laugh) at the way advertisers misuse English. They’re protected, of course, by the myths that surround their profession. If they get their grammar wrong, or misuse an idiom, they must have some ingenious marketing reason for doing so—or so people are willing to asusme. In fact, I think what’s happening is that the lousiness of the American educational system is trickling up into the ranks of copy writers and copy editors and basically everyone in the chain of custody of commercials.

The one that got me writing this post is a Verizon radio ad, specifically an ad for Verizon’s phone/cable/Internet triple package. It features the usual fake testimonial sound-bites from actors pretending to be customers. That’s par for the course, until one of them says (and the stuff in square brackets is a paraphrase; the rest is verbatim):

“[Verizon gives you a great deal,] providing all three services and not pulling any punches.“

I love the image of a Verizon repair person coming to my door and slugging me in the jaw, as hard as he or she can. (I’d rather it not happen, but I love the image.) It is, of course, completely clear that the person who wrote that line has no idea what the expression “pulling a punch” actually means, and neither do the executives who paid to have the ad written. I surmise that they think it means “pulling a stunt”, so that not pulling any punches means you’re entirely honest. Or something. Who knows?

I suppose that if Coors can actually bring to market a product called “Artic [sic] Ice”, then Verizon can sleepwalk through the process of producing radio commercials. In fact, it doesn’t surprise me any more. I no longer expect the ostensible gatekeepers to know what they’re doing. They probably never did, but I do think it’s gotten worse. And funnier.

In 1964, the great film theorist Christian Metz published a seminal essay called, “Le Cinéma: langue ou langage?” The basic idea was this. Movies obviously communicate something. So they’re evidently tapping into the human capacity for understanding symbolic representation—essentially, language. But does that mean that there is a film language, with its own precise rules, the way there is English or French? Or does it mean, rather, that film participates in the process of communicating in a language-like way, but not according to one particular set of rules?

Metz’s view was that it was the latter. Film communicates through language-like means (symbolic representation, piecing shots and scenes together like phrases to create meaning), but there’s no one-and-only language called Film. Different films can do it differently, and different audiences (depending on when and where they learn to become “film literate”) have different ways of interpreting the content and editing patterns of films.

Thus one may say that film is langage (language-like communication), but it is not une langue (a particular language).

It strikes me that this goes to the heart of the L in DSL.

DSLs a-go-go

The concept of the Domain Specific Language (DSL) has been in heavy rotation in recent times in the Ruby and Rails worlds, and for good reason. Ruby provides a very hospitable environment for little idiom sets that, with little effort, can be coaxed into looking like pseudo-code or configuration syntax, and therefore can help greatly in allowing non-programmers to understand what’s going on.

Thus, for example, you might come up with something that allows you to do this:

with Employee "123-45-6789" do
  dock_salary 1000
  warn_about :misconduct
end

and you can be fairly optimistic that, with minimal coaching, you can get most people to understand it.

This kind of thing is extremely useful. I wonder, though, whether it always deserves to be called a Domain Specific Language. It seems to me that the term DSL has become a bit over-burdened. It sometimes feels like any snippet of code that uses a block and includes one or more well-named methods ends up getting called a DSL.

In the grand scheme of things it doesn’t really matter if someone happens to call a snippet of code a language, domain specific or otherwise. But I do think that the horizon of DSL expectation in Ruby has shrunk a little bit. If DSL means having a method called warn_about that doesn’t need an explicit receiver (and, by the way, I myself dislike the magic instance_eval trick that allows this; but that’s another story), then we don’t really have a name for full-blown, semantically rich, domain-specific languages written in Ruby.

What the ‘ell?

It’s a bit curmudgeonly, though, to lobby for people to stop using a term they find appropriate for their code. So I haven’t. But this morning I thought of another way to see the whole thing.

This:

with Employee "123-45-6789" do
  dock_salary 1000
  warn_about :misconduct
end

is not a domain specific language. It is, rather, domain specific language. Note the lack of the “a”. It’s domain specific, and it uses language-like constructs. But it isn’t a language. It’s Ruby, using expressive method names and cushy semantics and therefore facilitating the use of domain specific idioms.

In other words, I suggest that when people say they have created a DSL, they might more precisely say that they have used DSL. They have not created une langue, but they have made use of a particular aspect of langage.

Anyway, that’s how I’ve come to see it. I hope the late, great Metz would have approved.