Using What instead of Why to report errors

During peer code reviews I have sometimes observed that there is a preference for programmers to interpret errors or exceptions as part of the error handling process. Instead of reporting what caused the error, an interpretation is applied and why the error occurred is reported instead.

As an example, an exception such as "connection failed" is reported as "the server is down". This is, quite clearly, a naive interpretation. There may be many other reasons as to why the "connection failed"; the connection credentials may be incorrect, there may be a network fault, the service application may not be running or a solar flare may be affecting your Wifi. Under these circumstances, all you can safely assume about the situation is that, well, the "connection failed".

The example above seem obvious but it becomes even easier to make the mistake when reporting business exceptions from a web service. When required to handle a particular error, the programmer often has to rummage through a toolbox of available business exception codes and apply the one that fits best. More often than not it doesn't.

The importance of getting this right may only become apparent after that prolonged phone call with the irate user who insists that your "server is down" when you know perfectly well that it isn't.

posted by James Gemmell on Wed, 01 Jun 2011 at 21:14 | permalink | tags: java, soap, spring