I have debugged many programs during my career, and I have assisted many others in debugging programs. I have also seen many people fail to get their programs working. I’m going to use this article as a means of helping others to get their programs to work. To put it bluntly, the best debugging tool and the one that must be used is a good attitude.

Will Rogers often said “It isn’t what we don’t know that hurts. It’s what we know that ain’t so.”1 (Yes, I know that others said similar things before him, but a video of Will Rogers is where I first remember hearing it.) When debugging software, there are many bad attitudes that people believe are actually good attitudes. Believing in things that are false will cause problems, and refusing to reconsider is a bad attitude.

A good attitude would be to seek methods and processes that are appropriate for debugging software. Other entries will discuss how to debug once you have a good attitude. For the moment, let’s discuss a few common beliefs.

Debugging Is Not Agile

There are people who will say the appropriate means of fixing bugs is to use Agile Scrum or one of the other Agile methodologies. Saying that Agile is the best for all situations or even that it is appropriate for all situations is a bad attitude.

The acronym INVEST (independent, negotiable, valuable, estimable, small, testable) has been mentioned as a means of determining whether a story is appropriate for Agile, while the acronym SMART (specific, measurable, achievable, time-boxed) is used to evaluate goals.2 Let’s first investigate the suitability of debugging as an Agile story.

  • Independent — One error in coding may result in multiple bug reports and a single bug report may actually involve several errors in coding.
  • Negotiable — Bugs are symptoms of coding and design errors. However, you don’t know how serious the errors are until you find the error. When you go to a medical doctor, small symptoms can be signs of serious illnesses, and the doctors run tests until they find the cause. If you don’t know how serious the problems are, you can’t determine which bugs have the highest priority.
  • Valuable — At last we have one for the positive column. Debugging is valuable.
  • Estimable — Finding the cause of a bug may take just a few minutes or it may be weeks.
  • Small — Since the effort required to fix a bug is virtually impossible to predict in advance, you certainly aren’t safe in saying which problems will be small ones.
  • Testable — On the positive side, it is possible to see if a fix removes the appearance of a bug. However, it may not be possible to test whether the root cause of a bug has been fixed.

Debugging Requires Doumentation

There are people who say that there is no need to prepare documentation when debugging because the Agile Manifesto states “Working software over comprehensive documentation”.3 There are a few problems with this attitude.

  • The manifesto mentions working software. If the software was working, you wouldn’t need to debug it.
  • The manifesto mentions comprehensive documentation. So they are really talking about the amount and kind of documentation.
  • Another statment reads “Individuals and interactions over processes and tools.” I interpret this to mean that you must reconsider the agile methodology if it interferes with individuals getting their work done or interacting with each other.
  • If all items on the left are more important than all items on the right, the last statement would mean that processes and tools have very little value. If that is what you believe, why do you believe that the agile process is valuable?

By the way, if I have to debug a program with no documentation, the first thing that I do is to read the software and make notes. Another word for those notes is “documentation”.

Other bad attitudes

Before the complaints start, I want to make it clear that there may be some validity to some of the comments listed below. You are going to have to release software at some point. However, the following types of statements are often used as excuses for releasing software way too early. You need to be able to justify these rather than using them as excuses.

  • It’s not my job — If you have a problem and it’s not your job to fix it, whose job is it? Are they actually working on it and are they able to do it? Is it a problem for you if nobody does it? If it’s not a problem for you but is a problem for the organization, aren’t you part of the organization?
  • It’s good enough — I follow a simple rule of thumb: if somebody says it’s good enough, it usually isn’t. A similar attitude is feeling that there is nothing that you can do to make it better.
  • We don’t have to worry about that — The classic case for this is not worrying about errors in the subroutine libraries, the data provided to the programs, or the ability of other programs to utilize the data your program generates. This is a bad idea. (I have found that when people say say something goes without saying, I really do need to say it.)
  • We can’t risk anyone learning that we made errors — If nobody made errors, you wouldn’t have to fix it. The users are usually going to find out about the errors later. If you find and fix the errors before the users find them, the users won’t know you made any. If your team can’t survive anyone finding out that anyone made errors, you have big problems. The only way you can truly cover yourself is with success.

The Scientific Method

I was trained as an engineer. So I approach debugging as simply another engineering problem. A good starting approach is the scientific method, using the following steps.

  • Collect information — Collect information about the bugs and the software that you are trying to use. To the extent possible, this information should be collected in a format that can be processed by automated procedures. Some of the information will be the bug reports, the source code, log files, knowledge about the subject matter, and knowledge about the automated systems used by the process.
  • Analyze collected information — Go through the information to try and detect patterns. In some cases, it may be possible to use automated tools to help with the analysis.
  • Generate potential hypothesis — Potential hypothesis would include possible locations where problem might occur, and possible situations which might result in errors.
  • Design experiments — Possible experiments would be creating test data sets and situations. Inserting code to create messages and using debuggers is equivalent to adding instrumentation in a physics experiment.
  • Run experiments and evaluate hypothesis — After you run your experiments (tests), evaluate the original hypothesis.
  • Create a potential fix and test it — Use the information to put fixes in the code, and see if the problem goes away.
  • Continue until everything works