Don't fix the bug...yet!

Why fixing that bug should be delayed


You've just finished coding a project and the code is being tested.  You find an erroneous error message, or an error is flagged that you didn't expect.  You whip into Bug Fixing mode, hunt down the cause of the issue, and slap in some code to fix that problem.  Tadah!  All is well again!

But you've missed an opportunity: unless you have diligently forced your code down every error path, you've got code paths that you have never explored.  Before you fix that bug, you have a unique opportunity to make sure that code path does exactly what you want it do.

The fact is, bugs are in your code—there is no getting around them.  Unexpected system interactions, unexpected user input, and sun spots all affect the code in ways you didn't imagine when you wrote it.  Given that you can't fix all the bugs, what you want is a reliable way to handle them.  You want an error reporting system that tells you exactly what went wrong, where it went wrong, and gives you a clear idea how to fix the problem without having to recreate the issue or spend time in a lengthy exploratory debugging session.

So, don't fix the bug right away.  Keep in mind how you want to fix the bug, and give yourself a bit of time to explore the error .

Is the text of the error message clear?
You have the error code and/or error message.  Take a moment to look at that message: is it clear to the user what action they should perform?  "Unexpected Error" conveys no information.  Rid yourselves of useless error messages.  Every time you find one of them, take the opportunity to convert it into an error message that tells you where the failure is and what the likely causes of the failure are.

Make sure the spelling is correct, that the message identifier is correct and documented, and that the syntax of the message is proper.  Error messages that are phrased "Unexpected Error, unknown, failure of" might have made sense when you wrote them but really, they just garble your intent.  Fix the content, then language, then the spelling.

Is that the error message you want?
You've caught the code in an unexpected position.  Is that the message you want to write when it gets there?  You might have a message that says "Unexpected Error, this should never happen", or "Unexpected Error call Bob at (800)123-4567", but this isn't what you really want to say when the error happens.  Now that you know what causes the failure and understand the code so that you can project what else might cause execution to reach this spot, make an error message that says what happened, why, and how to fix it.

Is that where you want the error to be detected?
You now understand the problem and you know what had to happen to get here.  Think about it for a second and see if maybe you couldn't have caught this issue earlier.  Is there a better way to head off this issue?  Was this the result of a subtly bad user input?  Could you screen the user input better and flag this earlier?

If you do redirect the error handling, make sure that works too.  If you've got an error stack (you do have one, don't you?), make sure all the messages in the stack make sense, are written correctly, and convey information too.

Leave some comments behind.
Oh, and comment what you've found.  You spent all that time tracking down the error and what happens when.  Leave yourself a note about how things flow so you don't have to rethink all this stuff again.


Then fix the problem
You've got the error handling worked out: the code is following the correct paths and detecting the issue as early as is feasible, don't forget to fix the problem.

It gets better
Diligently applying this method will make your code better and more readable. It will make your error messages more useful.  It has one added bonus for code that has loads of bad error messages: .it concentrates your efforts on errors that actually happen.