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?

15 thoughts on “An XML Design Dilemma

  1. Well, let me try to find some arguments. The second solution offer a structure which is regular: this is actually an array. You take just take this item and send an iterator over it to process this collection.

    The first solution is not regular. You have 3 single value, and then a list of actions. You cannot process with one simple iterator the container of those informations ( in case one).

    The first solution just mixt heterogeous data structure as one bag of information which will be more difficult to process automatically than the second.

    Hope that help…

  2. Bernard,

    I agree with that the second solution is more regular, and I suspect that is why I like it, but why is regularity good. Is it because regularity is usually easier to understand? In this case there is very little chance that either of these XML documents will be mis-understood. How do you justify the “cost” of the extra element. While the cost is very small the gain non-existent from a functional stand-point. If I want to iterate over the action elements I am going iterate over all the elements matching a particular xpath in either case, the only difference being the xpath. :/

  3. Ok, I will try some extreme investigation. What software initially address is automation of human process. People with strong software development background have unconscious, brain-cabled, analysis patterns to evaluate how good is a representation of the real-life in term of possible automation. We look at a repetition as an opportunity for a loop. The opportunity appears as soon we see 3 same “objects”. Two could be hard-coded (real-life is full of pairs: left/right, next/prev, front/back…). Three is an automation blasphemy (no reason it stops at 3, we know it will comes to 4, 5…). I think this is the reason why I feel uncomfortable in front of a mix of objects with at least 3 objects of the same type. So maybe the main reason your second xml is better is that it gives a better opportunity for automation.

  4. Olivier is right, however I share his arguments only when complexity raises, not before. I would have added the “available action” not at the first iteration of the design, but whenever appears the need for a differentiation between types of actions : forbiden action, hidden action, whatever. When you only got one type of action, I dont’t feel like your design “lowers” the complexity. However it can generate this new concept in people’s mind .. like “eh, he’s right ! aren’t there some other types of actions here ?”.

  5. Pierre, I agree that the availableActions element does not lower the complexity. That is, fundementally, my problem. I see that it does not lower the complexity but still I feel that it is a better design. As you point out, the grouping of available actions does allows for the format to be extended more easily in the future. Perhaps that is why it feels better to me.

  6. Here is my take on this question : from a computer point of view, both designs are equal. In both cases, you can return the list of actions with a simple XPATH expression.

    I don’t believe the second design allows for better extension because you don’t know what the future will be like. So you don’t know for sure that your design will accomodate for it. On my defense, I believe in just-in-time design (= design for the present moment).

    To me, the second design looks better because it is more human readable.

  7. To resolve quickly such dilemma, I apply a “distance to limit balance” principle.
    I don’t look for why a solution is better than another one, but I try to estimate each solution limit as a design limit over there it will not work and I reject the solution where the limit is the more probable (the closest to my current context as a system of constraints).

    For example :
    Limit for the 1st solution : grouping actions involves a structure refactoring
    Limit for the 2nd solution : extra characters (~40o) cost is 1 for 1000 messages/second for a SLA of 100 message/second.

    The distance to limit of the 1st solution seems to be closer to you than the second one. Hence, the second solution seems to be the best at the current time, because the second solution push far the limit. People like to be free of…constraints, isn’t it?

  8. Gilles, maybe the human readability is the best argument. I think that argument, while correct, is a bit tenuous. It is not really difficult to read the first form. I guess you could say that since the cost of the extra element is negligible, even a marginal improvement in readability warrants the change, but it feels a bit contrived to me.

  9. Julien, interesting approach. Unfortunately, in this case I think that neither design would ever reach its limits. It is quite unlikely that any refactoring will ever be required and the volume of messages will be measured in messages/week rather than per second.

  10. Pingback: Bernard Notarianni
  11. When you parse those two xml snippets, the first could have actions interspersed with other event elements (since XML is unordered); the second would have all of the actions grouped together. It’s all the same to a machine (give or take), but much easier for a human to deal with.

  12. Tim, you are correct that the second form is only easy to read because the elements are ordered in a particular way. However, XML is not unordered. There is a defined order to any document (document order) and in with XML scheme you can, and in most cases do, define a required order to the elements (a ‘sequence’ in XML schema requires that element occur in the specified order for the document to be valid). Therefore, the schema for the documents could easily specify that the action elements could only occur at the end of the document.

    On the other hand, you, I and, I think, most other people tend to think of XML documents as unordered (actually, we tend to treat the orderedness as a bug to be ignored/worked around) and, as far as I can tell, very few people actually validate their documents so depending on the order required by the schema is pretty much just folly. Unless, of course, all the software involved is controlled by the same team, which in this case it is.

    Still I think the readability argument is the best one. The second from is more readable and is more resistant to obfuscation.

  13. > Re: Gilles comment at September 26th, 2005 at 2:10 am:
    > “Here is my take on this question : from a computer point of view,
    > both designs are equal. In both cases, you can return the list of
    > actions with a simple XPATH expression.”

    They’re not equal, from a computer’s perspective, if you drop the assumption that you’ll use XPATH to find them, and the assumption that there will never be elements at a deeper level. For example, in the future, an action could describe further actions that could be taken after this one. Those nested actions would be enabled (or excluded) by this one.

    The first XML mixes elements of two different types: Attributes (identifier, type, description) and the elements of a set or array of actions. But the “set or array” is missing from the XML. Grouping the elements in an element simplifies the view from the element to its children. Consider a tree view of the XML, where you can expand or contract each node. In IE, for example, I can display this data like this:

    | –
    | 1234
    | ForkReached
    | There is a fork in this path. Which way do you want to go?
    | …
    | …
    | …
    |
    |
    | –
    | 1234
    | ForkReached
    | There is a fork in this path. Which way do you want to go?
    | +
    |

    And then, *IF I’m interested in the detailed list of actions, I can chose to look at them:

    | –
    | 1234
    | ForkReached
    | There is a fork in this path. Which way do you want to go?
    | –
    | …
    | …
    | …
    |
    |

    That’s why it’s better.

    (And it’s also worse… Because Word messed with the quotes and ellipses in the second XML. ;-)

  14. For me, as a non-XML-savvy person, I think the second XML is indeed better. And it has to do with readability. But why?

    I have two slightly different explanations for why the readability is better in the second XML. One, it gives me a context for the actions (“What are these? Oh, they’re available actions. OK.”). Two, it introduces a mental concept (available actions) which quickly leads me to investigate if this is a complete list or if there should be more actions available – it sort of focuses my thinking. (Which is only good if the concept introduced is good – which, in this case, it is.)

Comments are closed.