subbu.org

Most of us consider exception management one of the simplest issues in programming. Since exceptions are easy to throw and catch in programming languages like Java, exception design rarely takes priority in design discussions. Not surprisingly, one of the least considered aspects of designing exceptions is usability. Yes, usability of the API being designed should be the primary focus when designing and implementing exceptions. This is more so when the software is layered, like most software today is.

Recently I had to spent several hours debugging some third-party software. Most of the issues I faced are due to misconfiguration and poorly explained/documented APIs. Sometimes exceptions did not make sense. Sometimes components did not work as expected, and left little or no clues. Some exceptions occurred much later than the cause, making it more difficult to connect the cause to the exception. I don’t think I am alone with this experience.

Most developers are also users of APIs designed by other developers. Are those developers so mean to other developers, and want them to suffer? I think the problem is due to a lack of attention to usability of their APIs and implementations.

Imagine you are making coffee with a coffee maker. The steps are very simple. You pour the beans, or ground coffee, you pour water, make sure it is plugged in, and switch it on. Within a few minutes, your coffee will be ready. What can go wrong in this process? Very few things can wrong with a coffee maker (assuming that the coffee maker is not a dollar store kind). The very few things that can go wrong can be fixed by doing things right, such as not forgetting to pour water, checking that the coffee maker is actually plugged in, etc.

Now imagine the same coffee maker in software, with an ICoffeeMaker interface like this.

public interface ICoffeeMaker {
public void plugin();
public void addWater(Water water);
public void addBeans(BeanScoup beans);
public void registerCarafe(ICarafe carafe);
public void makeCoffee();
public void plugout();
}

Let us write a simple coffee maker application using an implementation of the ICoffeeMaker interface.

ICoffeeMaker coffeeMaker = ICoffeeMakerFactory.getInstance().getCoffeeMaker();
Water water = new Water(4); // Four cups
BeanScoup beans = new BeanScoup();
coffeeMaker.addBeans(beans);
coffeeMaker.addWater(water);
coffeeMaker.plugin();
coffeeMaker.registerCarafe(myCarafe);
coffeeMaker.makeCoffee();

We could also add a listener that would alert the caller when the coffee is ready. If everything goes well, the coffee maker would pour the coffee into the registered carafe object, and call the listener when the coffee is ready.

Most likely such a coffee maker would be layered on top of several other components, such as a power source (IElecticPower), a heater (IHeater), water level sensor (IlevelSensor), and so on. Each of these components may in turn be layered on top of several other components, depending how those are implemented. It is quite reasonable to expect most of those components are sophisticated and have complex implementations with lots of features. It is also quite possible that those components have several knobs (e.g. configuration files), and setup requirements.

Let us get all the components required by the coffee maker, configure through some build files, write our coffee maker class, and compile it. We are now ready to make coffee. Before we run the coffee maker, let us see what can go wrong, so that we can handle those conditions properly and tell the user what went wrong.

If we follow the hardware version of the coffee maker, we could expect similar issues such as a NoWaterException, or a MissingCarafeException, or a NoPowerException. But as a user of the ICoffeeMaker, you would not expect any of the following.

• A NullPointerException from the IHeater implementation.

  java.lang.NullPointerException:
  at com.heaterco.impl.electric.HeaterImpl.warm(HeaterImpl:1250)
  at com.heaterco.impl.electric.HeaterImpl.start(HeaterImpl:94)
  at com.coffeeco.impl.m1343.CoffeeMakerImpl.preMake(CoffeeMakerImpl:495)
  ...
  at com.coffeeco.impl.CoffeeMakerImpl.makeCoffee(CoffeeMakerImpl:234)
  ...
  

  There is nothing strange about this exception, except that it does not tell what went wrong, and what you, as a user of the ICoffeeMaker interface should do about it.

• An XML parser exception from within a ILevelSensor layer.

  com.sensorinc.fluid.ConfigException: The markup in the document following the root element must be well-formed.
  at com.sensorinc.fluid.SensorImpl.init(SensorImpl.java:103)
  ...
  Caused by: org.xml.sax.SAXParseException: The markup in the document following the root element must be well-formed.
  at com.sun.org.apache.xerces.internal.parsers.DOMParser.parse(DOMParser.java:264)
  at com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderImpl.parse(DocumentBuilderImpl.java:292)
  at javax.xml.parsers.DocumentBuilder.parse(DocumentBuilder.java:98)
  at test.Service.load(Service.java:53)
  ... 18 more
  

  This exception is slightly better than the previous one as it at least tells that some config file is misconfigured. It still does not tell you where the file is located in your classpath or the file system.

• Here is another one, caused by the same misconfiguration.

  java.lang.NullPointerException
  at com.sensorinc.fluid.SensorImpl.init(SensorImpl.java:131)
  ...
  

  Here the misconfiguration of the sensor surfaced as a NullPointerException due to a coding error in SensorImpl. This one is harder to debug, and you will need the source of the sensor to figure out what went wrong. More lost hours.

There is a pattern in all these three examples.

• None of these exceptions are part of the ICoffeeMaker interface. The user of the coffee maker would not expect any of these. But since software is malleable, exceptions like this can happen.
• There is little info on how to fix the exceptions. The developer(s) of these components paid no attention to how exceptions are reported and propagated to callers of their APIs. In essence, they did not care deeply about usability of their software.

What is the remedy? If you are the user of the APIs, there is probably nothing you can do about it, other than getting used to those exceptions and learn by experience, or pick another API/implementation.

For people developing APIs for others to use, I would like to make a few suggestions.

• Pay more attention to exception design and propagation. When propagating an exception, leave clues. Provide as much information as possible of the cause. Make the cause obvious.
• Exceptions of part of the interface. So the exceptions must convey meaning.
• Users of the APIs use exceptions to augment their understanding of the APIs. The more pleasant you make their experience, the more they will love your APIs and promote them. So, please be nice to your users.

If the API designers and implementors of the coffee maker components paid more attention, the stack traces would have looked like the following

• com.heaterco.electric.NoPowerSourceException: Heater cannot be warmed. There is no power source connected. Check your power source.
  at com.heaterco.impl.electric.HeaterImpl.warm(HeaterImpl:1250)
  at com.heaterco.impl.electric.HeaterImpl.start(HeaterImpl:94)
  at com.coffeeco.impl.m1343.CoffeeMakerImpl.preMake(CoffeeMakerImpl:495)
  ...
  at com.coffeeco.impl.CoffeeMakerImpl.makeCoffee(CoffeeMakerImpl:234)
  ...
  

  In the original stack trace, the developer did not check if the power source is null before continuing.

• com.sensorinc.fluid.ConfigException: Sensor config sensor.conf.xml misconfigured. The cause is "The markup in the document following the root element must be well-formed.".
  at com.sensorinc.fluid.SensorImpl.init(SensorImpl.java:103)
  ...
  Caused by: org.xml.sax.SAXParseException: The markup in the document following the root element must be well-formed.
  at com.sun.org.apache.xerces.internal.parsers.DOMParser.parse(DOMParser.java:264)
  at com.sun.org.apache.xerces.internal.jaxp.DocumentBuilderImpl.parse(DocumentBuilderImpl.java:292)
  at javax.xml.parsers.DocumentBuilder.parse(DocumentBuilder.java:98)
  at test.Service.load(Service.java:53)
  ... 18 more
  

  This exception atleast tells that there is configuration file sensor-conf.xml that is invalid.

• I added the third exception to merely illustrate that exception propagation needs more attention. Here is the code snippet that probably caused the NullPointerException.

  Sensor sensor = null;
  try {
  // Load the configuration
  
  // Set config data on the sensor
  sensor = new ...;
  sensor.setId(...);
  ...
  }
  catch(...) {
  throw new ConfigException("Sensor " + sensor.getId() + " misconfigured");
  }
  

  Since the sensor object not initialized yet, we now have new exception masking the misconfiguration issue. This is a coding error. But trust me, this happens.

Since most discussion on exceptions include the checked vs unchecked question, let me say that unchecked exceptions are not bad. They just deempasize usability little more, because compilers do not enforce propagation or handling. Your kitchen could get flooded if the dam at the hydro-electric power plant crashes and the dam engineers used unchecked exceptions in their design.