Define the Problem

Assuming that you have determined the need for a debugging effort, it's important to approach the effort with a plan rather than with a hit-or-miss, haphazard approach. This chapter will lay out a methodology that you can apply to any type of debugging or troubleshooting effort.

Following a plan or method is often viewed as taking too long or being too involved by software professionals. Most often, they'd rather just jump in and fix the problem rather than take the time to go through a lot of useless steps. Sometimes this is actually the case in simple, straightforward problems. The problem is that it is not always possible to identify the simple cases. Problems that appear simple may in fact be quite complicated, and problems that appear intractable may indeed be simple.

It is overkill to go through complex debugging procedures when a single, acute error occurs. If you do something that generates an obvious, "Jeez what a stupid mistake" type of error message, just go ahead and correct it and go about your business. There will be times when you'll be fooled by this, however, and find out that your "simple" problem is really a symptom of something else. Knowing the difference between when to do the quick fix and when to dig deeper is the part of debugging that falls more into the art of debugging as opposed to the science of debugging. If you're doing quick fix, view it as the first step in the debugging process and don't claim that its fixed until other problems have had time to manifest themselves or work themselves out.

Understand the Specifications

In order to troubleshoot a system adequately, the debugger must first be sure she understands the way the system is actually supposed to behave. In the case of the OnLine engine, the higher-level specifications are pretty simple and straightforward. The user makes a request and the engine executes it. If it doesn't execute the request, there's a probably a problem somewhere.

Where this gets more complex is when the troubleshooter is expecting one type of behavior and receives something totally different. For example, you may be trying to achieve parallelism by tuning the engine's PDQ priorities. When you make a database request, you'll usually get some sort of response from the engine, but the path that the engine takes to get the response will differ based on your PDQ settings. Unless the person trying to tune the system knows exactly what to expect in the way of number of threads, priorities, and response times, he will have a hard time determining whether the system is behaving correctly.

The same situation arises in debugging custom-written code. If you don't know exactly what the code is supposed to do and how it is supposed to do it, you will be at a marked disadvantage in your troubleshooting efforts.

Get First Hand Reports

Make sure that you fully understand the problems that are presented to you. Don't ever try to debug a system without a clear, unambiguous description of the problem. Try to deal with the people who actually discovered the problem. If you get into a situation of "John said that Mary said that such-and-such a process took too long," you need to be talking to Mary, not John. Actually you need to be sitting beside Mary while she duplicates the problem herself.

Poor communications are the bane of the software debugger. We've all probably played the old party game of "rumors" in which someone starts out by telling a story to one person, who then tells it to another and so on until the story gets back to the originator. This final story often bears little resemblance to the original story. The same principles apply to troubleshooting and debugging. By the time that the report goes through several interpreters, much of it will be either incomplete or totally wrong. Human communication is an imperfect process, and this imperfection is magnified by every person in the chain. Go to the source.