Experienced software developers do all that they can during development to ensure that the software works. But they also know that, despite their efforts, there will be mistakes, and they plan for that from the start.
A common way to plan for mistakes is to add statements to a program that show what is going on in enough detail that mistakes can be detected and diagnosed. You want to turn on the lights rather than working on your software in the dark. Typically, trace statements write where a program is and what is in selected variables or data structures.
Once a unit is found to work, you do not remove the trace prints. Nor do you comment them out. After all, you might want to use them again.
Leave the trace prints in the program. When you add a trace print, surround it by a test such as
if(tracing > 0)
{
…
}
where tracing is a global variable. If
that variable is 0, traces are skipped. You turn them
all on merely by setting tracing to a positive
integer. Often you have levels of tracing, depending
on how much detail you want to see. For example,
if(tracing > 1)
{
…
}
says only to do this trace print for level 2 or higher.
You can also have more than one variable to control tracing. You typically have a variable for each module or collection of related modules. You can even test multiple variables. For example,
if(tracing > 0 && traceQueueModule > 1)
{
…
}
only does the trace if tracing is turned on and
traceQueueModule has level 2 or higher.
Never print raw numbers in a trace print. A trace print should normally contain the following information.
Remember that there will, in general, be many trace prints in your software. Each one should say where it is by giving the name of the method (and possibly the module) in which it occurs. A typical way to do that in method insert is
if(tracing > 0)
{
System.out.printf("insert: …");
}
showing the name of the method as if you are writing
a play and this is a line for it to speak.
Say where this trace occurs in the method. Is it at the beginning? The end? At the top of a loop body?
Provide relevant information. If you are showing the size of something, write "size = …", where … tells the size. Be sure to include important information. You will want to see it for diagnosing problems.
Make traces readable. Do not run consecutive traces all onto one line. Put spaces between different pieces of information. Unreadable trace prints are worse than useless.