Home (Spotlight) | TOC | Products & Ordering | Technical Info | Contact Zeus

Zeus Tech Note
Trouble-Shooting and Debugging

(This document last revised August 1, 1997)

Copyright © 1996-1997. Zeus Productions. All Rights Reserved.
Written by Bruce A. Epstein

trouble-shoot: v. to isolate and diagnose the source of an error.

debug; v. to systematically challenge your assumptions until a problem is resolved.

Debugging is a skill that comes naturally to some people, but can be learned be all. Whether you are a programmer, a psychologist, a doctor , a plumber, or a car mechanic, your job involves debugging. You must diagnose a problem and fix it.

Humans are natural problem-solvers, and you surely employ debugging techniques unconsciously many times each day. Once you understand the process of debugging you will be able to apply it consciously to all aspects of your professional and personal life.

We'll use examples from a variety of different disciplines because the same techniques apply across the board. We'll also look at it from a computer perspective.

Define the Problem

The first step towards fixing a problem is to determine its exact nature. To say "it is broken" is not very helpful.

Key Technique: State the nature of the problem clearly, and the circumstances under which it occurs. Be specific.

Example: My child throws temper tantrums.

Assuming your child does not throw temper tantrums 24-hours per day, define the issue more precisely. Such as, "My child throws temper tantrums when we go shopping."

Key Pitfall: Mistaking a symptom for the problem.

Your child is probably throwing a temper tantrum because they are sick, tired, hungry, or jealous. The tantrum is just a symptom of a problem that may be easily addressed by a simple schedule change. Likewise the tics and random noises common to Tourette's Syndrome patients are symptoms. Telling a Tourette's patient to be quiet or stop twitching is unlikely to help.

Computer Technique: Identify the specific steps or circumstances under which the problem occurs. Does your program crash when you print a document, or only if you print a document containing graphics? Write out the specific steps in a bug report that allow someone to reproduce the error.

Define the Desired Outcome

You can't work towards or implement a solution efficiently until you have defined your goal. You have to keep your "Eyes on the Prize".

Key Technique: State the specific outcome you hope to achieve.

Example: I want my teenage daughter home by ten o'clock.

You may actually want to prevent your daughter from getting pregnant, but have focused on the time she gets home instead. Is it acceptable for her to bring her boyfriend home at ten o'clock to neck on the couch? If you focus on the wrong issue, you won't really solve the problem.

Key Pitfall: Unintended consequences.

Most actions have consequences which are either unexpected or unintentional. What if your teenage daughter runs away from home rather than obey your strict curfew?

Computer Technique: It is not always clear what constitutes success. Many programmers focus on fixing specific bugs that have been reported to cause crashes. You must also consider whether the application performs adequately. If a solution will compromise performance unacceptably, you must include such criteria in your definition of success.

What if you've only tested your product with one printer? Does it need to work with other printers. Success may be defined not as, "Get it to print," but "Get it print in under 10 seconds at 600 dpi on a all major laser printers."

Measure Success

You must not only define success, you must measure whether you have actually acheived it.

Key Technique: Develop a method that verifies what you want to test.

Example: I want my teenage daughter home by ten o'clock.

You may actually want to prevent your daughter from getting pregnant, but have focused on the time she gets home instead. Is it acceptable for her to bring her boyfriend home at ten o'clock to neck on the couch? If you focus on the wrong issue, you won't really solve the problem.

Key Pitfall: Unintended consequences.

Most actions have consequences which are either unexpected or unintentional. What if your teenage daughter runs away from home rather than obey your strict curfew?

Computer Technique: It is not always clear what constitutes success. Many programmers focus on fixing specific bugs that have been reported to cause crashes. You must also consider whether the application performs adequately. If a solution will compromise performance unacceptably, you must include such criteria in your definition of success.

What if you've only tested your product with one printer? Does it need to work with other printers. Success may be defined not as, "Get it to print," but "Get it print in under 10 seconds at 600 dpi on a all major laser printers."

Be Realistic

or setting an impossible goal.

Assuming your child does not throw temper tantrums 24-hours per day, define the issue more precisely. Such as, "My child throws temper tantrums when we go shopping."

Declare victory and get out.

Do Your Homework

Do Some Measurements
Identify Likely Causes

Key Technique: Identify

You Can't Fix a Problem You Can't Find

Key Technique: Be systematic. Check one thing at a time.

Conduct a systematic examination of each component in the system.

Try to narrow down the problem by determining what does work, which will leave you with a better understanding of where the problem lies.

You cannot

Don't overloork the non-obvious - search deeper.

Key Technique: Be systematic. Check one thing at a time.

The Most Common Sources of Error are the Easiest to Fix

Key Technique: Don't overlook the obvious.

The most common programming error is a syntax problem or typographical error, such as an incorrect file name or file path. Verify and physically retype the command or file path to make sure that they are correct.

If your computer, printer, hard drive, or monitor doesn't work, make sure it is plugged in, that the power is on, and any cables are connected properly.

Narrow the Problem Down

Key Technique: Isolate different components to eliminate them as potential sources of the error.

Locating the error gets you half way to solving it. If not, you have gained useful information and narrowed down the possible sources of error.

Consult the documentation, FAQs and examples provided
Test on a system that is as "clean" as possible. Quit all other applications. Temporarily disable other Xtras or XObjects. Reboot to make sure that you have a fresh start.
Test on another machine to determine if the problem is machine-specific.
Test with a well-worn version of the operating system. Avoid older versions, or brand new untested versions, or systems with beta software installed.
Test with a different application to determine if the problem is application-specific
Make sure you have sufficient RAM to determine if the problem is memory-related.
Make sure that you have the latest version of the application. Re-install if necessary.
Test it at a different color depth, such as 256 colors or thousands of colors.

Windows Specifics:

Test on both Windows 3.1 and Windows 95 to see if it is peculiar to the Windows OS.
Test it on several 486s and a Pentiums to determine if the problem is particular to one machine or processor.
Test a Windows 3.1 (16-bit) projector, and a Windows 95 (32-bit) projector to determine if the problem is projector-specific.
Test it on a system with a different video card.

Macintosh Specifics:

Test on both a 68K Mac and PowerPC Mac to see if it is dependent on the processor type.
Restart with Extensions disabled (hold down the Shift key when restarting)
Test a 68K projector, and PowerPC projector and a Fat Projector to determine if the problem is projector-specific.
If using a two-monitor setup, test it on a single-monitor system to eliminate the second video card as the source of the error. If you have a second video card installed, it may have some effect, even if a second monitor is not hooked up.

How can I narrow down the problem?

The best approach depends on the nature of the symptoms. If there is smoke coming out of your computer, re-installing the software probably won't help. It is common to have no idea where the problem lies, so you have to start somewhere based on what you know. Conceptually, the trouble-shooting process is always the same, whether you are fixing your car, your body, your computer or your love life.

Define what is not working
Decide what would constitute a satisfactory solution
Delineate the major components of the system
Discover which components are working or and which are not
Debug the broken component

How do I know where to start?

Start with the most likely causes that are easiest to check, and eliminate possibilities as you progress.

Possible sources of error fall loosely into the following categories:

Likely to be the problem and easy to check
Unlikely to be the problem, but easy to check
Likely to be the problem, but difficult to check
Unlikely to be the problem, and difficult to check

One generally assumes that components that have previously worked are still working. For example, if your printer has worked reliably for years and suddenly stops printing, you might assume that the cable has come loose. On the other hand, if the printer never worked, you might think it was damaged in shipping, or that the wrong cable is being used.

If something works partially or intermittently, this often represents the greatest challenge. Suppose a printer provides poor output. It could be something obvious such as the laser printer is low on toner, or something more subtle, such as the wrong type of paper being used.

The most difficult categories to solve are:

Intermittent problems which are hard or impossible to reproduce
Problems that are beyond your control, such as basic incompatibilities between third party hardware or software
Problems which don't conform to the basic assumptions we have made. For example, if you follow the documentation, assuming it is correct, when in fact the documentation is at fault. Another example might be a problem caused by intermittent power surges, whereas the common assumption is that your outlet works properly.

How do I actually check the suspected culprit?

As with any undertaking, it helps if you have the right tools and a modicum of patience and experience. Sometimes there is no way to verify or fix a problem without the right tools. One tried and true approach is to substitute a known working part for the suspected culprit. For example, if your printer does not work with your cable, but another cable works, then you know that your cable is at fault.

This can be extraploated to other areas. It is generally easy to swap printers, monitors, cables and even computers. It is somewhat more difficult to swap

Once I have determined the problem, how can I solve it?

After you have determined what is going wrong, you can make a guess at its cause. An error may be easy to fix, such as a simple syntax error. Consult the documentation for the proper syntax, make the correction and try the application again.

Other possible solutions fall loosely into the following categories:

Likely to work and easy to implement
Unlikely to work, but easy to implement
Likely to work, but difficult to implement
Unikely to work, and difficult to implement

Why can't I get it to work on all machines?

This is one of the great questions of all time. If you can get your project to work on 90% of installed base of PCs you are doing well. If on the other hand, your project is failing on every PC, the problem is most likely with your Lingo code, an Xtra or your Projector.

For example, most GPFs are caused by conflicts with audio and video card drivers or a misconfigured system. Encourage users to upgrade their drivers, and/or use the Generic VGA 640x480x256 video driver that is available from Microsoft (it ships with Windows for Workgroups, and can be downloaded from Microsoft too).

You should obtain the details of the user's configuration (i.e. make, processor, video and sound cards/drivers, available RAM, etc.) and contact Macromedia regarding known problems with the given hardware/software setup. They maintain a KnowledgeBase which probably has known configuration specific conflicts listed. They also provide a list of known good and bad video cards in a text file that comes with Director called VIDSOUND.WRI.

Consult the Director for Windows README files regarding creating a custom DIRECTOR.INI file that may help in certain situations.

Zeus Tech Note Trouble-Shooting and Debugging