NOTE: this will generally pertain to C#
but applies to any programming language which uses similar exception
handling (for example Java). This article covers a few misconceptions about exceptions and is not intended as a complete reference. In depth study of this important programming aspect is highly recommended.
Overview
The exceptions a method throws are as
important as its parameters or return value. They are part of your
contract with the user, even if you are not required to declare them
as part of your method definitions (as you are in Java). Too often
methods are completely written before any thought is given to the exceptions it should throw. This unfortunate behavior leads to a less than ideal interface for the user.
Many developers believe, and in many
cases are taught, exceptions exist to handle rare or infrequent
conditions encountered during execution. The truth is as developers
we have no control over the circumstances our code is used in beyond
the compiler enforcing the existence of our parameters. As such we
can never say what the frequency of any use case may be. Thus we can
never say if any given case is rare or common.
Usage
The correct use of exceptions is to
convey our inability to keep our contract with the user as defined by
our method signature. Let us consider the following method signature
from the Int32 type:
public static int Parse(string s)
This method takes a string
representation of an integer and returns its integer representation.
Viewing the documentation reveals it throws the following exceptions:
ArgumentNullException – thrown when s
is null.
FormatException – thrown when s
cannot be converted to an int.
OverflowException – thrown when the
representation of s is beyond the capacity of an Int32 to represent.
Each of these exceptions represents a
condition which prevents the method from honoring its contract,
returning an integer representation of the string parameter, to the user. There is a different exception for
each semantically meaningful mode of failure. That is to say each
exception represents a different reason the conversion failed giving
the caller the ability to make a meaningful decision about how to
proceed. The OverflowException can represent failure due to either a
value above or below what can be represented by an Int32. As the user
would not take different actions based on whether the
value is too big or too small we have just one exception to represent
both instead of an OverflowHighException and an OverflowLowException.
Example
Using these ideas let us design our own
method. Let us suppose we have a type which represents a temperature
probe. We might start by writing a class method with the signature:
public float GetTemperature()
[Note: normally we would use a property here but for demonstration purposes we will make this a method. Also, interestingly enough, the CLR doesn't know about properties so C# converts them into methods during compilation]
What exceptions should this method
throw? Anything which violates our contract with the user should be
represented by an exception. In this case any condition which would
prevent us from returning a temperature will need an exception. We
could start with the following:
TemperatureProbeNotAvailableException – thrown if our connection to the probe is lost.
TemperatureOffScaleException – thrown if the
probe provides a value beyond what its specification states it can
accurately measure.
Previously when considering the Parse
method we said there was no need to have multiple exceptions to
represent the high and low possibilities for the OverflowException.
Here we also have a single exception to represent an out of range
condition. Considering further is there any action our users might
wish to take based on whether the temperature probe is off scale high
vs low? In this case there is.
If the probe were attached to a heating or cooling system knowing which direction the temperature
is off scale would be very meaningful information. For a more awesome
example let us say this was a very high temperature probe in the
exhaust of a gas turbine engine. Many such probes do not operate
correctly until they reach a minimum temperature well above normal
ambient. An off scale low condition might be normal while the engine
was offline or idle but an off scale high might indicate the engine was running
beyond specification and should be throttled down.
Since the direction of the off scale condition is
potentially meaningful to the user we should provide exceptions for
these conditions.
public class TemperatureOffScaleHighException
: TemperatureOffScaleException
public class TemperatureOffScaleLowException :
TemperatureOffScaleException
Though the off scale direction of the
temperature probe could be useful to
the user this might not always be the case. By extending the high
and low exceptions from the TemperatureOffScaleException we give the
user a choice If they do not care about the direction of the off
scale condition they can choose to catch the base
TemperatureOffScaleException. Otherwise if they have code to handle
the high and low conditions differently they may catch these derived
exceptions in separate catch blocks and deal with them as they see
fit.
Aren't Exceptions Time Expensive?
Depending on the environment the throwing of exceptions can be time expensive, especially if they repeatedly do so in tight loops. The previously mentioned Int32 type addresses this with the TryParse method.
public static bool TryParse(string s, out int result)
This method does not throw a FormatException. Instead if will return a boolean indicating if the conversion was successful and if so it will provide the converted value via the result out parameter. By using a boolean instead of an exception this call avoids the cost associated with handling an exception.
Does this method keep its contract with its user? Yes it does.
Whereas the Parse method implies by its signature it will return a converted value TryParse implies it will attempt a conversion. This distinction in naming is important in creating an API your users will be able to easily understand.
A simple look through the FCL will demonstrate the occurrence of TryX is very limited. While the TryX methods seem to match the X method in capacity and excel it in speed it fails in code simplicity. The code necessary to support the TryX method is more cumbersome than the a simple X method.
Conclusion
There are various opinions about the role of exceptions and how they are used. What I would like to convey here is exceptions are an important yet overlooked aspect of development in environments which support them. A more in depth study than what is presented here is recommended though simply considering them at the outset of development instead of as a postscript will help in API design.
