I Keep Making Changes and It Makes No Difference

If the REPL says there is an error and you don’t see it, that might be because you and the REPL are not looking at the same code. Check your programming environment to make sure that the program you are editing is the one Julia is trying to run.

If you are not sure, try putting an obvious and deliberate syntax error at the beginning of the program. Now run it again. If the REPL doesn’t find the new error, you are not running the new code.

There are a few likely culprits:

• You edited the file and forgot to save the changes before running it again. Some programming environments do this for you, but some don’t.

• You changed the name of the file, but you are still running the old name.

• Something in your development environment is configured incorrectly.

• If you are writing a module and using using, make sure you don’t give your module the same name as one of the standard Julia modules.

• If you are using using to import a module, remember that you have to restart the REPL when you modify the code in the module. If you import the module again, it doesn’t do anything.

If you get stuck and you can’t figure out what is going on, one approach is to start again with a new program like “Hello, World!” and make sure you can get the known program to run. Then gradually add the pieces of the original program to the new one.

My Program Does Absolutely Nothing

This problem is most common when your file consists of functions and classes but does not actually invoke a function to start execution. This may be intentional if you only plan to import this module to supply classes and functions.

If it is not intentional, make sure there is a function call in the program, and make sure the flow of execution reaches it (see “Flow of execution”).

My Program Hangs

If a program stops and seems to be doing nothing, it is “hanging.” Often that means that it is caught in an infinite loop or infinite recursion. Here are a few tips that can help you identify the problem:

• 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 “Infinite loop”.

• Most of the time, an infinite recursion will cause the program to run for a while and then produce an ERROR: LoadError: StackOverflowError error. If that happens, go to “Infinite recursion”.

  If you are not getting this error but you suspect there is a problem with a recursive method or function, you can still use the techniques described in that section.

• If neither of those steps works, start testing other loops and other recursive functions and methods.

• If that doesn’t work, then it is possible that you don’t understand the flow of execution in your program. Go to “Flow of execution”.

while x > 0 && y < 0
    # do something to x
    # do something to y
    @debug "variables" x y
    @debug "condition" x > 0 && y < 0
end

When I Run the Program I Get an Exception

If something goes wrong during runtime, Julia prints a message that includes the name of the exception, the line of the program where the problem occurred, and a stacktrace.

The stacktrace identifies the function that is currently running, and then the function that called it, and then the function that called that, and so on. In other words, it traces the sequence of function calls that got you to where you are, including the line number in your file where each call occurred.

The first step is to examine the place in the program where the error occurred and see if you can figure out what happened. These are some of the most common runtime errors:

ArgumentError

One of the arguments to a function call is not in the expected state.

BoundsError

An indexing operation into an array tried to access an out-of-bounds element.

DivideError

Integer division was attempted with a denominator value of 0.

DomainError

The argument to a function or constructor is outside the valid domain.

EOFError

No more data is available to read from a file or stream.

InexactError

The value cannot be converted exactly to a type.

KeyError

An indexing operation into an AbstractDict (Dict)- or Set-like object tried to access or delete a nonexistent element.

MethodError

A method with the required type signature does not exist in the given generic function. Alternatively, there is no unique most specific method.

OutOfMemoryError

An operation allocated too much memory for either the system or the garbage collector to handle properly.

OverflowError

The result of an expression is too large for the specified type and will cause a wraparound.

StackOverflowError

The function call grew beyond the size of the call stack. This usually happens when a call recurses infinitely.

StringIndexError

An error occurred when trying to access a string at an index that is not valid.

SystemError

A system call failed with an error code.

TypeError

A type assertion failure has occurred, or you’ve called an intrinsic function with an incorrect argument type.

UndefVarError

A symbol in the current scope is not defined.

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: 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.

To simplify the program, there are several things you can do. First, scale down the problem the program is working on. For example, if you are searching a list, search a small list. If the program takes input from the user, give it the simplest input that causes the problem.

Second, clean up the program. Remove dead code and reorganize the program to make it as easy to read as possible. For example, if you suspect that the problem is in a deeply nested part of the program, try rewriting that part with a simpler structure. If you suspect a large function, try splitting it into smaller functions and testing them separately.

Often the process of finding the minimal test case leads you to the bug. If you find that a program works in one situation but not in another, that gives you a clue about what is going on.

Similarly, rewriting a piece of code can help you find subtle bugs. If you make a change that you think shouldn’t affect the program, and it does, that can tip you off.

My Program Doesn’t Work

Ask yourself these questions:

• Is there something the program was supposed to do but that 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.

• 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 effect that is not what you expected? Make sure that you understand the code in question, especially if it involves functions or methods in other Julia modules. Read the documentation for the functions you call. Try them out by writing simple test cases and checking the results.

In order to program, you need a mental model of how programs work. If you write a program that doesn’t do what you expect, often the problem is not in the program; it’s in your mental model.

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

Of course, you should be building and testing components as you develop the program. If you encounter a problem, there should be only a small amount of new code that is not known to be correct.

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, this:

addcard(game.hands[i], popcard(game.hands[findneighbor(game, i)]))

can be rewritten as:

neighbor = findneighbor(game, i)
pickedcard = popcard(game.hands[neighbor])
addcard(game.hands[i], pickedcard)

The explicit version is easier to read because the variable names provide additional documentation, and it is easier to debug because you can check the types of the intermediate 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, if you are translating the expression $\frac{x}{2\pi }$ into Julia, you might write:

y = x / 2 * π

That is not correct because multiplication and division have the same precedence and are evaluated from left to right. So this expression computes $\frac{x\pi }{2}$.

A good way to debug expressions is to add parentheses to make the order of evaluation explicit:

y = x / (2 * π)

Whenever you are not sure of the order of evaluation, use parentheses. Not only will the program be correct (in the sense of doing what you intended), it will also be more readable for other people who haven’t memorized the order of operations.

I’ve Got a Function That 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 result before returning. Again, you can use a temporary variable. For example, instead of:

return removematches(game.hands[i])

you could write:

count = removematches(game.hands[i])
return count

Now you have the opportunity to display the value of count before returning.

I’m Really, Really Stuck and I Need Help

First, try getting away from the computer for a few minutes. Working with a computer can cause these symptoms:

• Frustration and rage

• Superstitious beliefs (“the computer hates me”) and magical thinking (“the program only works when I wear my hat backward”) *

• Random walk programming (the attempt to program by writing every possible program and choosing the one that does the right thing)

If you find yourself suffering 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 some 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 am away from the computer and let my mind wander. Some of the best places to find bugs are on trains, in the shower, and in bed, just before you fall asleep. ø

No, I Really Need Help

It happens. Even the best programmers occasionally get stuck. Sometimes you work on a program so long that you can’t see the error. You need a fresh pair of eyes.

Before you bring someone else in, make sure you are prepared. 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, be sure to give them the information they need:

• If there is an error message, what is it and what part of the program does it indicate?

• 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?

• What have you tried so far, and what have you learned?

When you find the bug, take a second to think about 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.

Remember, the goal is not just to make the program work. The goal is to learn how to make the program work.