The goodness of curl (and REST)

Tim Bray, in an post about testing atom protocol, said

We got two different clients to talk to it; one was a Big Secret Project from a Big Famous Company based on all sorts of slick infrastructure. Mine was curl. […] Those who know what curl is are probably snickering now. But I think the fact that you can debug a nontrivial application with curl -X -i -d -H is a significant weapon in the quiver of RESTafarians.

We are only snickering because we have done the same thing. When you are testing a RESTful application a big sophisticated client mostly just complicates things.

There is a huge advantage to technologies that can be worked with using existing, generalized and scriptable tools. That ability allows for easy testing and debugging, as Mr. Bray points out, but the advantages do not end once you are done debugging.

These days most people are employed to deal with abnormal situation. The normal situations are mostly automated and require very little human intervention. Having software that can be worked with and monitored by existing, scriptable, tools means the you have to write less code to handle those abnormal situations when they arise. If you are a RESTafarian, you just grab curl and a few minutes later you are done. Even better, if that abnormal situation is common enough to warrant it, you can even wrap it up in a script so that anyone can handle it.

An XML Design Dilemma

Recently the following XML was proposed during a design session of which I was part. This document basically says that something has happened that cannot be automatically handled. A program receives this XML and asks a human which of the available actions to take.

  <event>
    <identifier>1234</identifier>
    <type>ForkReached</type>
    <description>
      There is a fork in this path.  Which way do you want to go?
    </description>
    <action name="TakeMoreTraveledPath">
      ...
    </action>
    <action name="TakeLessTraveledPath">
      ...
    </action>
    <action name="ReturnHome">
      ...
    </action>
  </event>

I responded by proposing encapsulating the action elements in a availableActions element like this.

  <event>
    <identifier>1234</identifier>
    <type>ForkReached</type>
    <description>
      There is a fork in this path.  Which way do you want to go?
    </description>
    <availableActions>
      <action name="TakeMoreTraveledPath">
        ...
      </action>
      <action name="TakeLessTraveledPath">
        ...
      </action>
      <action name="ReturnHome">
        ...
      </action>
    </availableActions>
  </event>

To me the second is obviously better. However, I found that I was unable to come up with a single concrete reason why the second form is better than the first. Both are easy fairly to understand. Iterating over all of the actions is not hard (the same number lines of code) in either case. I can think of no functional difference between the two. So why, then, does the first form make me feel dirty?

While pondering this, I found this in a post on an unrelated topic.

I think there’s a watershed moment in every developer’s career when they start look more at their code as a structure and less as a bag of statements. — Jeremy Miller

I agree with Jeremy that there is a lot to be gained by focusing less on the the details and more on the structure. (The smalltalk people have know that for years, apparently.) Since I was still pondering my XML dilemma I immediately thought, “I like the availableActions element because it results in a document with a better structure.” But I did not manage to completely convinced myself. We usually think that one structure is better than another for some fairly concrete reason, like it will be more reliable or extensible. But in this case I cannot put my finger on why one of the options feels so much better than the other.

I wonder if this is common for developers to feel that one design is distinctly better than another without being able to articulate, in concrete terms, why. Does that happen to you often? If so how do you deal with it, especially in an XP environment where the design that feels better may, at least arguably, be a little bit less simple?

In this particular case am I wrong that the second flavor feels better than the first flavor? If I am correct about the second flavor feeling better is there some concrete reason why that I am overlooking?

Hungarian Good, Exceptions Bad?

I think Joel has got a good idea in Joel on Software – Making Wrong Code Look Wrong. Unfortunately, his implementation sucks.

I see his point about Apps Hungarian, in which you tag names with an indication of how the application uses it, but I think it clutters the code significantly. Fundamentally, Apps Hungarian is a kludge — and a pretty vile one at that — to get around the fact that common languages lack the really important feature of type aliasing. “rwMax” is fine but so is “maxRow” and I find the latter a bit easier on the eyes (camel case grips aside). It would be nice is if you could have a type named RowNumber, which was really just another name for an integer, but in this case you probably want to included row or col(umn) in the var name anyway, just to make it obvious. In my experience this is accepted practice, but perhaps not followed as often as it should be. Either you use names that look like “rwMy” or “MyRow”.

As for his example web app, I have a much better solution than his. Rather than crufting up the names in your code the interfaces you used should be domain specific. The idea of making it obvious when returning text provided by user without HTML encoding it first can easily be achieve by creating an HTML writer class (or module). At it’s most basic this class would have two methods, write(), which HTML encodes the string before writing it, and writeUnencoded(), which writes the string with no modifications. With this design using writeUnencoded() with constants or literals is always okay, but using writeUnencoded() with variable is suspicious. So every time you see

htmlOut.writeUnencoded("<br />")

It is correct.

htmlOut.write("<br />")

It is probably wrong.

htmlOut.write(name)

It is correct.

htmlOut.writeUnencoded(name)

It is probably very wrong.

This solution is better in several respects: bad code smells bad, it makes doing a dangerous thing more difficult than doing safe things and it is not subject to breakage by newbies that have not learned your naming conventions yet. Using Apps Hungarian gets you bad code smells bad (but only if both the reader and writer are intimately familiar with the prefixes being used), but it does not encourage to you to do the right thing. One of the rules I use is dangerous operations should be indicated as such and the equivalent safe operation should be easier to find and/or use.

As for exceptions, Joel is not completely wrong that throws are a bit like GOTOs. But they are still a better way to program. I think most of this ground has been covered but having to check the result code of every method or function you call is not a good approach to producing code that is understandable, and failing to do that in a non-exception environment is a sure way to end up with unstable code. Fortunately, Joel has already lost this argument because most programmers use exceptions and have found that while they may occasionally cause unexpected behavior they are a big win, with regards to both code understandability and stability.

Enterprise Application Integration As Dispute Resolution?

Sean McGrath has an interesting view of EAI. Basically he thinks is all about dispute resolution.

Computer system A sees the world one way, computer system B sees the world another way, computer system C has a third way and thinks A and B are deeply wrong in how they see the world. etc. etc. The custodians of systems A, B and C need to work together for the good of the greater organization.

That fits pretty well with my experience.

Code as Design (Redux)

In this article I proposed that coding is design and not construction. As usual I am late to the party, Jack Reeves pointed this out 13 years ago (thanks Charlie), it discussed extensively on c2.com (What Is Software Design and The Source Code Is The Design), and mentioned on many blogs.

The whole thing has depressed me a bit. I think our industry would be in a lot better shape if we had internalized this idea 10 years ago. Why is it that good ideas, like this one, do not take hold? Anyway, if you have not read those essays by Jack Reeves go do it now.

Coding Is Not Construction

The other day I was talking to a colleague and I compared software development with building a building. I have heard this analogy often and there are a lot of similarities. (For example, most buildings and software systems are, at least partly, custom.) I think there is much to be learned from this analogy when correctly applied, however it is more often than not mis-applied and when it is it leads to all sorts of false conclusions.

The basics of this analogy are that building construction and software development have the following phases:

Inception
Someone has an idea about what to build.

Design
An architect/engineer designs the building or software by drawing a set of picture and writing some text about the thing to be built.

Construction
A bunch of labors use the documents produced in design step to produce the final product.

Profit!
Sell the building or software.

People often equate the construction to coding when applying this process to software development. The RUP process, for example, uses these phases. But coding is design, not construction. The construction phase of building a building is more equivalent to compiling in software development. This is a bit easier to see if you look at what the output of a project is. In a building project the output is the building. In a software development project that output is it is the executable, and it’s supporting data, not the code. In the software industry we have already completely automated the construction phase. I think that we already know, sub-consciously at least, that coding is not construction because we call systems like make, ant, etc. “build” tools, implying that they construct the final product.

When you write code you are not producing the final product, you are producing a set of instruction to the construction team — the compiler and build tool — in much the same way an architect of a build produces instructions in the form of a set of blue prints. This distinction may not seem particular important at first, but the, incorrect, equation of coding to construction leads to some bad conclusions. Some example are component-based software engineering and certain types of out-sourcing.

What we call designs in software development are more like the artist’s view of a building than what architects produce as input to the building construction phase. While these nice pictures are useful, I think we have done our selves a disservice by calling them designs. Calling them designs implies that all the necessary information for construction is present and it never is. Design choices keep getting made until the day you freeze the code.

If we want to improve software development what we need are better construction teams, not off-the-shelf walls or structural designs for each floor done in different lower-cost-countries. Architects do not have to design a house down to the detail software developers write code because physical construction teams can fill in a lot of detail by themselves. I think this is why DSLs are often a big win. The compiler (or interpreter) for the DSL can fill in a lot of detail based on the it’s understanding of the domain.

Fixed a couple of spelling errors.