Steve Vinoski's Blog

Via Stefan Tilkov: Assaf Arkin talks about his upcoming book, Ruby in Practice. I don’t know anything about the book, but it sounds interesting.

Assaf talks about having a nice Ruby interface for WS, and also talks about wrapping Websphere MQ with Ruby. It reminded me of some work I was doing about a year and a half ago, when I still worked for IONA: developing a Ruby wrapper for Artix. I left there before it ever saw the light of day, so I doubt anyone will ever see it, but it was pretty cool. It was implemented using only customer-visible C++ APIs, and it afforded at least an order of magnitude reduction in the number of lines of code required to get anything done. It used WSDL4R to interpret a WSDL definition at runtime and dynamically generate accessor functions for the service, i.e., there was no up-front static code generation. You could point the client at the service, and if the service supported access to its WSDL (typically via a ?wsdl query string added to the service URI), the client could download the WSDL and dynamically generate everything required to access that service. I wrote about how to develop such Ruby extensions in my Sep/Oct 2006 IC column.

I remember presenting an example of the system in an internal sales engineering meeting where the original C++ and Java code required 70-80 lines of code while the equivalent Ruby code was only 7 lines. It wasn’t 7 lines of obfuscated expert-only Ruby, either; it was quite easy to read and understand. The SEs, most of whom worked only in Java and C++, kept looking at it and scratching their heads. They’d say, “Hey, you forgot to do this!” and I’d say, no, that happens right here. And they’d say something similar about another required action, and the answer was always the same: no, it’s in there. Basically, Ruby allowed me to hide a bunch of crufty, verbose, uninteresting but required boilerplate and focus only on service interactions. Waaay nicer than the equivalent Java and C++, for sure.

On a related note, just prior to that project, I did some work with Apache CXF to develop a server-side JavaScript and E4X JAX-WS capability. Since I no longer work in the middleware or WS worlds, I haven’t kept track of that code, so I don’t know if CXF still supports it or not. But either way, given the fact that JRuby now exists, there’s no reason that someone couldn’t take that work and redo it in JRuby. It would be pretty straightforward.

Patrick Mueller responded to my previous blog posting on interface definition languages, and I wanted to comment on his response. Long ago Patrick was involved in defining the Smalltalk bindings for CORBA IDL, so he’s a CORBA veteran like me, and in the big picture we agree on many things. It’s nice having him cast a critical eye on this stuff.

Note that Patrick mostly talks about data schemas, whereas my posting talks only of interface definition languages. These are two very different things, which I’ve noted in comments on his blog. In a reply comment he said they’re both metadata, which is true, but still, they’re very separable. REST depends heavily on data definitions, but it doesn’t require specialized interface definitions because it promotes a uniform interface. For data definition REST relies on and promotes media/MIME types, and the standardization of such data definitions is critical to allowing independently-developed consumers and providers to interact correctly. I doubt Patrick and I really disagree on this last point.

One area where we apparently do disagree, though, is in the area of documentation. In my previous post I said that users of services ultimately rely on human-generated and human-readable documentation, not interface definition languages, to ensure their consuming applications interact correctly with those services. Patrick commented:

The documentation? What documentation? I’m picturing here that Steve has in mind a separate document (separate from the code, not generated from the code) written by a developer. But human generated documentation like this is still schema, only it’s not understandable by machines, pretty much guaranteed to get out of sync with the code, probably incomplete and/or imprecise. Not that machine generated schema might fare any better, but it couldn’t be any worse.

But there are more problems with this thought. The notion of hand-crafted documentation for an API is quaint, but impractical if I’m dealing with more than a handful of APIs.

I understand what Patrick’s saying here. Yes, documentation can get stale and out of sync. Still, I disagree. I’ve been near interface definition languages for at least 20 years now, and never once — not even once — have I seen anyone develop a consuming application without relying on some form of human-oriented documentation for the service being consumed. Such documentation might be as simple as a conversation with a developer across the hall, or reading comments in the definition language file itself, or might be from a README, email, a web page, a wiki, a Word document, a PDF, or a whole formal specification. I mean, what if the OMG had published only the ORB and Object Services IDL interfaces without the accompanying reams of human-oriented description and definition? Or if WSDL were enough, why the need for so many pages of human-oriented WS-* documentation?

Like I said in my previous post, interface definition languages exist for machines to generate code. They’re totally inadequate, though, for instructing developers on how to write code to use a service. The need for human documentation in this context isn’t quaint or impractical at all — it’s simply reality.