Writing Effective Exception Descriptions

Introduction

Writing exception descriptions are not really taught in programming classes but are vitally important in the field.  Namely if you need to refine your descriptions to find a problem it can lead to multiple pushes to a production environment before you actually fix the problem.  Depending on the issue this could waste valuable time.

Between reading about how to write good exception descriptions from various companies and my personal experience I've accumulated the following tips to share.  Note that most of the time exception text bubbles into your log files so some references to log files will be mentioned as well.

Be Layer-Centric

If you catch an exception and re-throw, describe the problem in the terms of the current (throwing) layer.  As an example, if you are writing TCP/IP library code and catch an IP exception, state your TCP problems.  If you are (ab)using TCP for Inter-Process Communication (IPC), state the process you are trying to reach.  I have mistakenly thought there was a networking error when a program couldn't connect to localhost before.

Not a Singleton?  Include your object ID

Imagine a case where there is a complex object with invariants.   With two instances of the class logging at the same it could easily appear to violate it's invariants or demonstrate impossible behavior.  Imagine your TCP class logging that it closed the connection and then that it read data successfully - this could be very confusing.  With object IDs you would log that client 1 closed the connection and client 2 read successfully - this makes much more sense.

Multi-threaded?  Include your Thread ID

Some times you need to trace the execution flow in a particular thread.  If you do not include your Thread IDs this is an impossible task to do via the logs.

Don't Trust Library Exceptions

Frequently exceptions generated by library, module or component code is not very descriptive.  Continuing with the networking examples I've had many HTTP exceptions with no more description than "Bad Request".  Note the lack of IP address, host name, or port.  Given that exceptions turn into logs that then can go into various applications (e.g. Splunk) I think the descriptions are generic due to security concerns.

Include Some Variables

Try to include one or two other things to help you track down a problem, knowing WHAT from following the recommendations above won't necessarily help you figure out WHY.

Make it easy

When you write your subclass consider including a String.format style constructor.  This would let you avoid having to do a String.format call on every exception you need to throw.  Alternatively you could make an ExecptionDescription builder that includes the object ID and Thread ID automatically.

Conclusion

In conclusion if you plan ahead and write descriptive exception messages that let you track the instance, the thread and some internal state you will be able to diagnose (possibly critical) issues much faster.