Appendix D Debugging

The best debugging strategy depends on what kind of error you have:

Syntax errors are produced by the compiler and indicate that there is something wrong with the syntax of the program. Example: omitting the semi-colon at the end of a statement.
Exceptions are produced if something goes wrong while the program is running. Example: an infinite recursion eventually causes a StackOverflowException.
Logic errors cause the program to do the wrong thing. Example: an expression may not be evaluated in the order you expect, yielding an unexpected result.

The following sections are organized by error type; some techniques are useful for more than one type.

D.1 Syntax errors

The best kind of debugging is the kind you don’t have to do because you avoid making errors in the first place. In the previous section, I suggested development strategies that minimize errors and makes it easy to find them when you do. The key is to start with a working program and add small amounts of code at a time. When there is an error, you will have a pretty good idea where it is.

Nevertheless, you might find yourself in one of the following situations. For each situation, I make some suggestions about how to proceed.

The compiler is spewing error messages.

If the compiler reports 100 error messages, that doesn’t mean there are 100 errors in your program. When the compiler encounters an error, it often gets thrown off track for a while. It tries to recover and pick up again after the first error, but sometimes it reports spurious errors.

Only the first error message is truly reliable. I suggest that you only fix one error at a time, and then recompile the program. You may find that one semi-colon “fixes” 100 errors.

I’m getting a weird compiler message and it won’t go away.

First of all, read the error message carefully. It is written in terse jargon, but often there is a carefully hidden kernel of information.

If nothing else, the message will tell you where in the program the problem occurred. Actually, it tells you where the compiler was when it noticed a problem, which is not necessarily where the error is. Use the information the compiler gives you as a guideline, but if you don’t see an error where the compiler is pointing, broaden the search.

Generally the error will be prior to the location of the error message, but there are cases where it will be somewhere else entirely. For example, if you get an error message at a method invocation, the actual error may be in the method definition.

If you don’t find the error quickly, take a breath and look more broadly at the entire program. Make sure the program is indented properly; that makes it easier to spot syntax errors.

Now, start looking for common errors:

Check that all parentheses and brackets are balanced and properly nested. All method definitions should be nested within a class definition. All program statements should be within a method definition.
Remember that upper case letters are not the same as lower case letters.
Check for semi-colons at the end of statements (and no semi-colons after squiggly-braces).
Make sure that any strings in the code have matching quotation marks. Make sure that you use double-quotes for Strings and single quotes for characters.
For each assignment statement, make sure that the type on the left is the same as the type on the right. Make sure that the expression on the left is a variable name or something else that you can assign a value to (like an element of an array).
For each method invocation, make sure that the arguments you provide are in the right order, and have right type, and that the object you are invoking the method on is the right type.
If you are invoking a value method, make sure you are doing something with the result. If you are invoking a void method, make sure you are not trying to do something with the result.
If you are invoking an object method, make sure you are invoking it on an object with the right type. If you are invoking a class method from outside the class where it is defined, make sure you specify the class name.
Inside an object method you can refer to the instance variables without specifying an object. If you try that in a class method, you get a message like, “Static reference to non-static variable.”

If nothing works, move on to the next section...

I can’t get my program to compile no matter what I do.

If the compiler says there is an error and you don’t see it, that might be because you and the compiler are not looking at the same code. Check your development environment to make sure the program you are editing is the program the compiler is compiling. If you are not sure, try putting an obvious and deliberate syntax error right at the beginning of the program. Now compile again. If the compiler doesn’t find the new error, there is probably something wrong with the way you set up the development environment.

If you have examined the code thoroughly, and you’re sure the compiler is compiling the right code, it is time for desperate measures: debugging by bisection.

Make a copy of the file you are working on. If you are working on Bob.java, make a copy called Bob.java.old.
Delete about half the code from Bob.java. Try compiling again.
- If the program compiles now, you know the error is in the other half. Bring back about half of the code you deleted and repeat.
- If the program still doesn’t compile, the error must be in this half. Delete about half of the code and repeat.
Once you have found and fixed the error, start bringing back the code you deleted, a little bit at a time.

This process is ugly, but it goes faster than you might think, and it is very reliable.

I did what the compiler told me to do, but it still doesn’t work.

Some compiler messages come with tidbits of advice, like “class Golfer must be declared abstract. It does not define int compareTo(java.lang.Object) from interface java.lang.Comparable.” It sounds like the compiler is telling you to declare Golfer as an abstract class, and if you are reading this book, you probably don’t know what that is or how to do it.

Fortunately, the compiler is wrong. The solution in this case is to make sure Golfer has a method called compareTo that takes an Object as a parameter.

Don’t let the compiler lead you by the nose. Error messages give you evidence that something is wrong, but the remedies they suggest are unreliable.

D.2 Run-time errors

My program hangs.

If a program stops and seems to be doing nothing, we say it is hanging. Often that means that it is caught in an infinite loop or an infinite recursion.

If there is a particular loop that you suspect is the problem, add a print statement immediately before the loop that says “entering the loop” and another immediately after that says “exiting the loop.”
Run the program. If you get the first message and not the second, you’ve got an infinite loop. Go to the section titled “Infinite loop.”
Most of the time an infinite recursion will cause the program to run for a while and then produce a StackOverflowException. If that happens, go to the section titled “Infinite recursion.”
If you are not getting a StackOverflowException, but you suspect there is a problem with a recursive method, you can still use the techniques in the infinite recursion section.
If neither of those suggestions helps, you might not understand the flow of execution in your program. Go to the section titled “Flow of execution.”

Infinite loop

If you think you have an infinite loop and you know which loop it is, add a print statement at the end of the loop that prints the values of the variables in the condition, and the value of the condition.

For example,

while (x > 0 && y < 0) { // do something to x // do something to y System.out.println("x: " + x); System.out.println("y: " + y); System.out.println("condition: " + (x > 0 && y < 0)); }

Now when you run the program you see three lines of output for each time through the loop. The last time through the loop, the condition should be false. If the loop keeps going, you will see the values of x and y and you might figure out why they are not updated correctly.

Infinite recursion

Most of the time an infinite recursion will cause the program to throw a StackOverflowException. But if the program is slow it may take a long time to fill the stack.

If you know which method is causing an infinite recursion, check that there is a base case. There should be some condition that makes the method return without making a recursive invocation. If not, you need to rethink the algorithm and identify a base case.

If there is a base case, but the program doesn’t seem to be reaching it, add a print statement at the beginning of the method that prints the parameters. Now when you run the program you see a few lines of output every time the method is invoked, and you see the values of the parameters. If the parameters are not moving toward the base case, you might see why not.

Flow of execution

If you are not sure how the flow of execution is moving through your program, add print statements to the beginning of each method with a message like “entering method foo,” where foo is the name of the method.

Now when you run the program it prints a trace of each method as it is invoked.

You can also print the arguments each method receives. When you run the program, check whether the values are reasonable, and check for one of the most common errors—providing arguments in the wrong order.

When I run the program I get an Exception.

When an exception occurs, Java prints a message that includes the name of the exception, the line of the program where the problem occurred, and a stack trace. The stack trace includes the method that was running, the method that invoked it, the method that invoked that, and so on.

The first step is to examine the place in the program where the error occurred and see if you can figure out what happened.

NullPointerException:

You tried to access an instance variable or invoke a method on an object that is currently null. You should figure out which variable is null and then figure out how it got to be that way.

Remember that when you declare a variable with an object type, it is initially null until you assign a value to it. For example, this code causes a NullPointerException:

Point blank; System.out.println(blank.x);

ArrayIndexOutOfBoundsException:

The index you are using to access an array is either negative or greater than array.length-1. If you can find the site where the problem is, add a print statement immediately before it to print the value of the index and the length of the array. Is the array the right size? Is the index the right value?

Now work your way backwards through the program and see where the array and the index come from. Find the nearest assignment statement and see if it is doing the right thing.

If either one is a parameter, go to the place where the method is invoked and see where the values are coming from.

StackOverFlowException:

See “Infinite recursion.”

FileNotFoundException:

This means Java didn’t find the file it was looking for. If you are using a project-based development environment like Eclipse, you might have to import the file into the project. Otherwise make sure the file exists and that the path is correct. This problem depends on your file system, so it can be hard to track down.

ArithmeticException:

Occurs when something goes wrong during an arithmetic operation, most often division by zero.

I added so many print statements I get inundated with output.

One of the problems with using print statements for debugging is that you can end up buried in output. There are two ways to proceed: either simplify the output or simplify the program.

To simplify the output, you can remove or comment out print statements that aren’t helping, or combine them, or format the output so it is easier to understand. As you develop a program, you should write code to generate concise, informative visualizations of what the program is doing.

To simplify the program, scale down the problem the program is working on. For example, if you are sorting an array, sort a small array. If the program takes input from the user, give it the simplest input that causes the error.

Also, clean up the code. Remove dead code and reorganize the program to make it easier to read. For example, if you suspect that the error is in a deeply-nested part of the program, rewrite that part with simpler structure. If you suspect a large method, split it into smaller methods and test them separately.

The process of finding the minimal test case often leads you to the bug. For example, if you find that a program works when the array has an even number of elements, but not when it has an odd number, that gives you a clue about what is going on.

Reorganizing the program can help you find subtle bugs. If you make a change that you think doesn’t affect the program, and it does, that can tip you off.

D.3 Logic errors

My program doesn’t work.

Logic errors are hard to find because the compiler and the run-time system provide no information about what is wrong. Only you know what the program is supposed to do, and only you know that it isn’t doing it.

The first step is to make a connection between the code and the behavior you get. You need a hypothesis about what the program is actually doing. Here are some questions to ask yourself:

Is there something the program was supposed to do, but doesn’t seem to be happening? Find the section of the code that performs that function and make sure it is executing when you think it should. See “Flow of execution” above.
Is something happening that shouldn’t? Find code in your program that performs that function and see if it is executing when it shouldn’t.
Is a section of code producing an unexpected effect? Make sure you understand the code, especially if it invokes Java methods. Read the documentation for those methods, and try them out with simple test cases. They might not do what you think they do.

To program, you need a mental model what your code does. If it doesn’t do what you expect, the problem might not be the program; it might be in your head.

The best way to correct your mental model is to break the program into components (usually the classes and methods) and test them independently. Once you find the discrepancy between your model and reality, you can solve the problem.

Here are some common logic errors to check for:

Remember that integer division always rounds down. If you want fractions, use doubles.
Floating-point numbers are only approximate, so don’t rely on perfect accuracy.
More generally, use integers for countable things and floating-point numbers for measurable things.
If you use the assignment operator (=) instead of the equality operator (==) in the condition of an if, while, or for statement, you might get an expression that is syntactically legal and semantically wrong.
When you apply the equality operator (==) to an object, it checks identity. If you meant to check equivalence, you should use the equals method.
For user defined types, equals checks identity. If you want a different notion of equivalence, you have to override it.
Inheritance can lead to subtle logic errors, because you can run inherited code without realizing it. See “Flow of Execution” above.

I’ve got a big hairy expression and it doesn’t do what I expect.

Writing complex expressions is fine as long as they are readable, but they can be hard to debug. It is often a good idea to break a complex expression into a series of assignments to temporary variables.

For example:

rect.setLocation(rect.getLocation().translate( -rect.getWidth(), -rect.getHeight()));

Can be rewritten as

int dx = -rect.getWidth(); int dy = -rect.getHeight(); Point location = rect.getLocation(); Point newLocation = location.translate(dx, dy); rect.setLocation(newLocation);

The explicit version is easier to read, because the variable names provide additional documentation, and easier to debug, because you can check the types of the temporary variables and display their values.

Another problem that can occur with big expressions is that the order of evaluation may not be what you expect. For example, to evaluate x/2 π, you might write

double y = x / 2 * Math.PI;

That is not correct, because multiplication and division have the same precedence, and they are evaluated from left to right. This expression computes x π / 2.

If you are not sure of the order of operations, use parentheses to make it explicit.

double y = x / (2 * Math.PI);

This version is correct, and more readable for other people who haven’t memorized the order of operations.

My method doesn’t return what I expect.

If you have a return statement with a complex expression, you don’t have a chance to print the value before returning. Again, you can use a temporary variable. For example, instead of

public Rectangle intersection(Rectangle a, Rectangle b) { return new Rectangle( Math.min(a.x, b.x), Math.min(a.y, b.y), Math.max(a.x+a.width, b.x+b.width)-Math.min(a.x, b.x) Math.max(a.y+a.height, b.y+b.height)-Math.min(a.y, b.y) ); }

You could write

public Rectangle intersection(Rectangle a, Rectangle b) { int x1 = Math.min(a.x, b.x); int y2 = Math.min(a.y, b.y); int x2 = Math.max(a.x+a.width, b.x+b.width); int y2 = Math.max(a.y+a.height, b.y+b.height); Rectangle rect = new Rectangle(x1, y1, x2-x1, y2-y1); return rect; }

Now you have the opportunity to display any of the intermediate variables before returning. And by reusing x1 and y1, you made the code smaller, too.

My print statement isn’t doing anything

If you use the println method, the output is displayed immediately, but if you use print (at least in some environments) the output gets stored without being displayed until the next newline. If the program terminates without printing a newline, you may never see the stored output.

If you suspect that this is happening to, change some or all of the print statements to println.

I’m really, really stuck and I need help

First, get away from the computer for a few minutes. Computers emit waves that affect the brain, causing the following symptoms:

Frustration and rage.
Superstitious beliefs (“the computer hates me”) and magical thinking (“the program only works when I wear my hat backwards”).
Sour grapes (“this program is lame anyway”).

If you suffer from any of these symptoms, get up and go for a walk. When you are calm, think about the program. What is it doing? What are possible causes of that behavior? When was the last time you had a working program, and what did you do next?

Sometimes it just takes time to find a bug. I often find bugs when I let my mind wander. Good places to find bugs are trains, showers, and bed.

No, I really need help.

It happens. Even the best programmers get stuck. Sometimes you need a fresh pair of eyes.

Before you bring someone else in, make sure you have tried the techniques described above. Your program should be as simple as possible, and you should be working on the smallest input that causes the error. You should have print statements in the appropriate places (and the output they produce should be comprehensible). You should understand the problem well enough to describe it concisely.

When you bring someone in to help, give them the information they need.

What kind of bug is it? Syntax, run-time, or logic?
What was the last thing you did before this error occurred? What were the last lines of code that you wrote, or what is the new test case that fails?
If the bug occurs at compile-time or run-time, what is the error message, and what part of the program does it indicate?
What have you tried, and what have you learned?

By the time you explain the problem to someone, you might see the answer. This phenomenon is so common that some people recommend a debugging technique called “rubber ducking.” Here’s how it works:

Buy a standard-issue rubber duck.
When you are really stuck on a problem, put the rubber duck on the desk in front of you and say, “Rubber duck, I am stuck on a problem. Here’s what’s happening...”
Explain the problem to the rubber duck.
See the solution.
Thank the rubber duck.

I am not kidding. See http://en.wikipedia.org/wiki/Rubber_duck_debugging.

I found the bug!

When you find the bug, it is usually obvious how to fix it. But not always. Sometimes what seems to be a bug is really an indication that you don’t understand the program, or there is an error in your algorithm. In these cases, you might have to rethink the algorithm, or adjust your mental model. Take some time away from the computer to think, work through test cases by hand, or draw diagrams to represent the computation.

After you fix the bug, don’t just start in making new errors. Take a minute to think about what kind of bug it was, why you made the error, how the error manifested itself, and what you could have done to find it faster. Next time you see something similar, you will be able to find the bug more quickly.

Like this book?

Are you using one of our books in a class?

We'd like to know about it. Please consider filling out this short survey.