How to make peace with error messages

At last, after all those hours toiling under the glow of the computer screen, your first script is completed. All those hours learning to code have finally paid off. Holding your breath, you enter the command to execute the script… only to have an error message appear on the screen. You shake your fist to the sky and curse whatever deities you believe in, but the error message remains unchanged, almost like it is staring into your soul…

Error messages != fun, or the Art of Debugging

Error messages happen to everyone. The causes of error messages vary; sometimes the error is caused by a bug hidden in the system, other times the error stems from the human typing at the keyboard. In every case, error messages can be frustrating and time consuming (For those of you who have hunted for hours to find that missing closing bracket in your script, you know the pain that I speak of). Error messages are here to stay no matter how thorough you are with your code, so you’ll need to know how to deal with them in an efficient manner.

Making bugs visible

The first step of debugging your script is to make sure that you’re actually receiving error messages when things go wrong. Depending on the language you use, you can change your error settings to output errors in a log, in the command window, on a web page, etc. You can also change how detailed the error messages are or even create custom error messages to help pinpoint where in the script the code is failing. If your script is not running and you don’t see any errors pop up, your best bet is to look at the documentation for that programming language for error reporting.

Speaking of documentation…

RTFM

For the purposes of this post, RTFM means “Read the Friendly Manual”. Most programming languages have various documentations available in both online and print formats. The documentation is a good place to start when you suspect that the error is caused due to syntax errors or a function that is not being used properly.

Example: You have a python script that is returning the following error when you run the script [1]

>>> while True print 'Hello world'
  File "<stdin>", line 1, in ?
    while True print 'Hello world'
                   ^
SyntaxError: invalid syntax

The  “SyntaxError: invalid syntax” tells you that your code is not formatted correctly and you have a little carrot pointing to the last letter on the print function, so one would assume that the error involves the use of print in the while statement in some way. A quick search on the python website shows the proper syntax for constructing the while statement:

while True: print 'Hello world'

Note that we were missing a colon between the expression (while True) and the suite (print ‘Hello world’)

Reading the documentation is also a good way to reduce errors, so it’s worth your time to seek out good resources about the language you’re using and study them before and while you’re building the script.

GIYF

GIYF – Google is your friend. Librarians have a love-hate relationship with Google for reasons that have been covered extensively elsewhere. Google, however, is a staple in the programmer’s life. Copy the error message, paste it in the search box, and you’ll receive a multitude of hits of varying quality. If I do an exact phrase search on the (very common) PHP error “Parse error: syntax error, unexpected T_VARIABLE”, Google comes back to me with around 82,200 results. That’s a lot of results to wade through. A good thing to remember is that the same criteria that many librarians teach their user in evaluating sites for research can be applied while seeking out help with troubleshooting errors. By applying what is taught in many Information Literacy sessions, you will quickly narrow down the number of sites to use in your bug squashing process.

Once you have done a few searches for errors in one language, you hopefully will have found a few web sites that are consistent in providing detailed, accurate information about troubleshooting errors.  Some sites and resources that have been useful when I tracked down various error messages:

Some library-related resources for those dealing with errors while working on various library modules/script libraries in various programming languages:

There are many other places where you can search for help which you will find in your error tracking time.

Now for some audience participation:

  • Do you have a resource that helped you with errors and bugs?
  • What errors have you come across with coding for library related projects, and how did you find a fix?

Please share in the comments below. Happy bug squashing!

 

[1] Error example from http://docs.python.org/tutorial/errors.html#syntax-errors