Article Discussion
Design Principles and XOM
Summary: Elliotte Rusty Harold talks with Bill Venners about the API design principles that guided the design of the XOM (XML Object Model) API.
3 posts.
The ability to add new comments in this discussion is temporarily disabled.
Most recent reply: September 16, 2003 9:44 AM by Richard
    Posts: 409 / Nickname: bv / Registered: January 17, 2002 4:28 PM
    Design Principles and XOM
    July 28, 2003 10:17 AM      
    Elliotte Rusty Harold says, "One very important thing is the principle of least surprise. It should always be very obvious what a method does. And in reverse, you should be able to immediately guess what the method is."

    Read this interview:

    What do you think of Elliotte Rusty Harold's design principles?
    • Erik
      Posts: 7 / Nickname: erikprice / Registered: March 27, 2003 2:05 AM
      Re: Design Principles and XOM
      July 30, 2003 0:48 PM      
      Honestly? I thought to myself, "man it sounds a lot like the mindset of a Python programmer!"

      I'm a Java programmer myself, and intend to read Elliotte's book as soon as I finish three others I am in the middle of. I had never heard of XOM before reading this series of interviews, and it sounds interesting. But in addition to Java, I also really like Python and use it for creating tools for use at work (or personal use). This particular quote really struck me as being in line with the Python maxim, "There should be one obvious way to do something". Another quote from the interview that sounded like a Python rule of thumb was, "I wanted to make the right thing very easy to do, and the wrong thing difficult or impossible to do."
    • Joe
      Posts: 15 / Nickname: jcheng / Registered: October 16, 2002 8:08 AM
      Re: Design Principles and XOM
      August 12, 2003 5:29 AM      
      >> If you look at the articles written about assertions at Sun's Java web site, JavaWorld, and elsewhere, what you see is people using them most commonly as a replacement for IllegalArgumentException and similar things. And that to me just seems insane. <<

      Well, at least a few people at Sun are sane:

      "Do *not* use assertions for argument checking in public methods. Argument checking is typically part of the published specifications (or contract) of a method, and these specifications must be obeyed whether assertions are enabled or disabled. Another problem with using assertions for argument checking is that erroneous arguments should result in an appropriate runtime exception (such as IllegalArgumentException, IndexOutOfBoundsException, or NullPointerException). An assertion failure will not throw an appropriate exception."

      The same doc gives a good reason for being able to disable assertions--because then you can feel free to put in computationally expensive checks without worrying about the performance impact in production.

      I do agree that many programmers use assert the way ERH dislikes--it's really a shame!
    • Richard
      Posts: 5 / Nickname: richardd / Registered: April 30, 2003 3:23 AM
      Re: Design Principles and XOM
      September 16, 2003 9:44 AM      
      I disagree with the general statement that assertions are of no use because they can be turned off. I believe they are excellent for that same reason. In the guide to assertions ( nowhere does it recommend replacing exceptions with them - they have new uses.

      For example, I have developed an API that reads in a byte array and lazily interprets the data to form various higer level data structures. These structures can be resolved into a byte array which should be identical if no changes have been made to the structures.

      I also have an invariant on a data struture that causes the structure to resolve eagerly and regerates the byte array. Running this invariant during normal execution is not feasible - it defeats the purpose of having lazy intialization of the data structures.

      My main motivation for doing this with an assertion is that I can disactivate the assertions. Performing this check is very costly - it can slow down usage by orders of magnitude. However, it's extremely handy for finding bugs.

      I could have written this as a unit test but I like the fact that it's very light weight and that regular users can activate it easily with a JVM switch. If I give the API to someone, I can just say "turn the -ea option on" and mail me the stack trace. Asking a user to run the unit tests is more laborious and also means I'd have to distribute junit with my production version of the API (or they would have to get it).

      The other thing I use assertions for is when I debug. I try to whittle down the stack trace by adding assertions at each point something isn't right. Unlike adding in "System.err"s, I'm quite happy to leave the assertions in because they're not bothering anyone. I actually prefer it if my unit tests fail on an assertion that is in my code rather than an assertion in the unit test. The reason is that the assertion is closer to the problem (thus easier to debug) and travels with my production release (so I get the debugging benfits desribed about).

      I agree that assertions are not good everywhere, but they definitely do have their niche.