我是否应该在我的方法中捕获“纯文档”目的的异常？

Question

Should I catch exceptions in my method for "purely documenting" purposes, thus encapsulating the error-documentation inside the method itself, or is that responsibility of the caller?

Suppose I call numerous other methods in my EncryptPackage() method, including the framework ones, which potentially throw numerous exceptions. I wrap everything in using blocks, so no need to catch exceptions for cleanup (or I use try/finally for cleanup). Should I catch the exception anyway, and provide the details about the context of that method, or is it the responsibility of caller method?

Here is the case one:

[Serializable]
class TestClassException : Exception
{
    public TestClassException() : base() { }
    public TestClassException(string message) : base(message) { }
    public TestClassException(string message, Exception innerException) : base(message, innerException) { }
}

class TestClass
{
    public TestClass() { }

    public void EncryptPackage()
    {
        try
        {
            DoSomething();
            DoAnotherThing();
        }
        catch (Exception ex)
        {
            throw new TestClassException("Error occurred during package encryption", ex);
        }
    }
}

class ConsumerExample
{
    public ConsumerExample() { }

    public void DoSomeStuff()
    {
        TestClass testClass = new TestClass();

        try
        {
            testClass.EncryptPackage();
        }
        catch (TestClassException ex)
        {
            System.Windows.Forms.MessageBox.Show(ex.ToString());
        }
    }
}

In this code, notice how the EncryptPackage() method catches all possible exceptions, just to "decorate the error text", with a "Error occurred during package encryption" text. EncryptPackage() here encapsulates the error-description logic.

And here is another technique:

class TestClass2
{
    public TestClass2() { }

    public void EncryptPackage()
    {
        DoSomething();
        DoAnotherThing();
    }
}

class ConsumerExample2
{
    public ConsumerExample2() { }

    public void DoSomeStuff()
    {
        TestClass testClass = new TestClass();

        try
        {
            testClass.EncryptPackage();
        }
        catch (Exception ex)
        {
            System.Windows.Forms.MessageBox.Show("Error occurred during package encryption.\r\n\r\n" + ex.ToString());
        }
    }
}

In this example, EncryptPackage() does not catch anything, because the caller documents the error case anyway with "Error occurred during package encryption.\\r\\n\\r\\n" message.

Please note that this is a very simplified example, in real world there will be numerous hierarchical classes, and exceptions will be propagating through the long call stack, so which method of catching exceptions is preferred? Second approach seems "cleaner", because the exception is handled in a layer where some "actual handling" (eg displaying to user) is going to take place. Call stack information would be preserved in exception object, so technically it will be possible to find out where exactly the exception was thrown. But... that does not seem as "well-documenting" as the first approach, where each level of abstraction adds its own description to the error, preserving the previous exception in an innerException member. In this case, when the execution leaves the TestClass layer, it already contains detailed description of the error that happened within this class . So this feels to be the better encapsulation of error-handling logic.

Which one to use?

Answer 1

There is a chapter on this in Effective Java :

Higher layers should catch lower-level exceptions and, in their place, throw exceptions that can be explained in terms of the higher-level abstraction. This idiom is known as exception translation.

Answer 2

I prefer your second example, mainly because it can signicantly reduce the amount of error handling code you have to write, especially if you are writing custom exceptions - with the first example you could end up with a lot of custom exception classes which do not give much benefit (you already have the call stack to tell you where the exception came from).

You might think it is nice to have a more descriptive error message, but who benefits from this? The end-user? Should you even be displaying exception messages to your user (and what language are you going to use)? A lot of the time the user just needs to know that there has been an internal error, and they should give up (restart), or try again. Do you the developer benefit? You are probably going to end up examining the call stack anyway with the source code in front of you, so you don't really need a more descriptive message, you can see for yourself what the code is doing at that point.

This is not a hard and fast rule. Most of the time I only catch exceptions at the top level, where I log them and report an error to the user. If you are reporting the exception directly to the user, then often the original exception does not benefit from translation, eg, if you try to open a non-existent file, then the System.IO.FileNotFoundException is descriptive enough so why translate it to something else? Do you really want to make the same judgement call ("I know better than the library author so I am going to translate their carefully crafted exceptions") for all of the gazillions of exceptions out there? I only catch exceptions lower down if I want to recover from them (generally not possible), or, very rarely, I want to translate them to a more descriptive exception.

In a layered architecture, it can make sense to translate exceptions between the layers, eg, catch exceptions coming out of the data access layer to a form suitable for the application layer, and similarly between the application layer and the user interface, but I don't know if you are working on that type of system.

If you want to document your exceptions, you should use the exception tag in the xml documentation for the method. This can then be used to general help files from the documentation, eg, using SandCastle .

Answer 3

As per @Sjoerd above, translate exceptions so they are in the same level of abstraction. In your case EncryptPackage should translate any lower-level exceptions itself, NOT the caller.

Say the lower-level exceptions were from a DB layer (say DBException). Would the caller expect to understand DBException? The answer is NO: the caller wants to encrpt a package, not a DBException. The lower-level exceptions should be chained INSIDE the higher-level exception for debugging purposes.

Finally, I know TestClassException is an example, but make sure the exception class describes the problem clearly: I, personally, don't like bland, generic exception classes (except to make a common base-class for other exceptions).

Answer 4

You should try/catch in few, easily distinguished situations:

• any method that can be invoked "externally", such as your app's entry point, UI events, multi-threaded calls and others. Put some log output or message on each and every catch you have. This will prevent your app from crashing (for the most part) as well as provide you or the user with some feedback on how to fix the problem.

• when you can really handle the exception. This means your app can, for example, opt for a secondary database or server URL, apply a different processing etc.

• when you want to prevent something optional from ruining the main workflow, for example failing to delete your temp file shouldn't cause your process to fail.

• there are probably some other places where you'll need a try/catch but these should be rare

Always combine error handling with a decent way of logging and/or messaging the user, don't let any exceptions info disappear because that's how you get apps and don't behave well for "no apparent reason" - at least the reason should be made apparent.

Also - don't use exceptions to control your workflow. There really shouldn't be any "throw"s unless there's absolutely no other way of doing something.