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?

Comments 14