Field Guide to debugging

Excerpt from a tutorial made during the p5.js 2015 conference by Luisa, Jason, Tega, Taeyoon and many more. Full document here

Debugging is creative act

Debugging is major part of the development process in any language. The word ‘debugging’ describes locating a bug in your program, and figuring out what exactly is going on when the code throws this error. At all levels programmers encounter bugs and will often spend more time debugging than actually programming the application. You can expect to spend a lot of time doing this and so it’s really important to develop good strategies for identifying and working through bugs as you learn p5.js.

debug

A bug is a gap

As Clay Shirky aptly describes a bug as “the moment when there is both a technical problem with your code as well as a problem with your mental picture of what is happening in your code.” It is both an error and a gap between the system and your understanding of it.

p5jscon.hackpad.com_pi3t2Unx5Tl_p.397331_1433002110228_undefined

As you program you will be shifting between many roles and perspectives. When designing the scope and process of your application you are an architect, when writing your code you are an engineer, when testing you are a vandal and when finding your bugs you have to be a detective.

p5jscon.hackpad.com_pi3t2Unx5Tl_p.397302_1432773026695_Screen Shot 2015-05-27 at 8.30.05 PM

Designing a program is like being an architect.
p5jscon.hackpad.com_pi3t2Unx5Tl_p.397331_1433003115692_undefined
Developing a program is being an engineer and building a house.

p5jscon.hackpad.com_pi3t2Unx5Tl_p.397331_1433003194369_undefined

Testing is being a vandal, trying to break the house(?)

p5jscon.hackpad.com_pi3t2Unx5Tl_p.397099_1432996227814_Vandal

Debugging is like being a detective, to figure out how and why things broke.

p5jscon.hackpad.com_pi3t2Unx5Tl_p.397331_1433003769452_undefined

Don’t panic. Change perspectives.

When you encounter a bug that you do not know how to solve, stop, pause and take a deep breath. Stand up, say hi to the dog, take a walk or if it’s late go get some sleep. When you are frustrated, tired and upset, you are not in a good frame of mind to learn or solve a problem.

To find your errors you will need to change perspectives and become the detective. The goal is to find out what the program IS doing, rather than why it’s not doing what it’s supposed to. We need to get the computer to show us what it’s doing.

The clues are in the values of variables and flow of program.

Observe the problem

Explain your problem.
Walk someone through the issue even if they themselves do not know how to program. If no one is around, draft an email explaining what you have done and breaking down what the problem is.

mail

You probably won’t need to actually send this email as often the act of writing it will help you to locate and identify what you need to do next. Some programmers have even been known to explain their problem to a friendly inanimate object like a rubber ducky.

duck

This is also a good time to add comments to your code that tell you exactly what each of your functions is doing.

Before you start changing things

Before doing anything: save a copy of your code that you can go back to.

safe

While debugging you are likely to introduce other problems, break things or accidentally delete good work.

Only ever change one thing at a time. As you debug you will be turning parts of your code on and off.

switch

Every time you make a change, test your program. If you make multiple changes before testing, you will not know which change has what affect and are likely to break things further.

switches

Check the basic stuff

Many bugs end up being very basic mistakes that are equivalent to forgetting to plug in the projector. These mistakes are so obvious they are often invisible. Check the dumb stuff like are you editing the file that you are actually running (and not, for example, editing the local file, and looking at a different file on the server)? Are all of your external files where you think they are? Are your file dependencies correct? Are there any typos in your paths? Check your server? etc.

"Why isn't my robot bringing me lemonade?" "OH. It's because I forgot to attach the left arm." (Check your file dependencies.)
“Why isn’t my robot bringing me lemonade?”
“OH. It’s because I forgot to attach the left arm.”
(Check your file dependencies.)
"Why isn't my robot bringing me lemonade?" "OH. It's because I was calling its office phone and not its mobile number!" (Are you testing the right file? e.g., local vs. server.)
“Why isn’t my robot bringing me lemonade?”
“OH. It’s because I was calling its office phone and not its mobile number!”
(Are you editing/saving the correct file?)

Identify and check any ‘Black boxes’.

A black box describes any part of your system you do not understand the inner workings of. For example, a library or perhaps a function that you have not written for yourself.

blackbox

Systematically take out each black box one by one and run your program. This will help to see if these parts of the program contain the error.

Add reporting

Error reporting is how your program tells you what it is doing. p5.js comes with some built-in error reporting that will tell you if you have made specific syntax errors.

console1

It is also useful to add in your own reporting using the console.log() function. To check your program flow add in console.log() statements to your different functions and parts of your code. Then when you look at your console you can see the order that things happen and where you encounter problems.

console3

It is also useful to add in console.logs() to print out values of variables so that you can see what they are doing.

Search for more help

So none of this works? There are many places you can look online to get more help.

Do a Google search, if you have had this problem chances are many other people will have too.

Search the Processing forum under the p5.js category. Consider that p5.js is very similar to processing so problems and solutions may be the same.

Development forums like Stack Overflow

Always look at existing answers before asking for support.

The First "Computer Bug". Moth found trapped in a Mark II Aiken Relay Calculator in 1947.
The First “Computer Bug”. Moth found trapped in a Mark II Aiken Relay Calculator in 1947.