Reporting a Software Problem

When reporting any software problem (to me or to anybody else), you need to include the following in in your report:

• What you did...
• What you saw...
• What you think the problem might be...

What you did

What version of the software are you using. Be specific:

• If it's a web site problem, when did it occur? What are the last 3 URLs you visited on the site? Does it happen repeatedly or did it just happen once?
• If it's a Java Cookbook problem, what day of what month did you you download it? Is there a version identifier in the file? Use ident to find it, or look for the string beginning with a dollar sign and "Id".
• If it's an OpenBSD problem, what version of the kernel and userland are you running: CD-ROM 3.X? Current Snapshot? Current built from sources?

If it's a Java Compilation problem:

• What file(s) you tried to compile? Did you change the file in any way?
• The exact command you used to compile it, including computer output showing what your CLASSPATH is actually set to at compile time.
• What version of the compiler? If you are using Sun's JDK/JSDK, the exact output of "javac".

If it's a Java runtime problem:

• Your classpath
• The command used to invoke it.
• The exact output, including the stack trace. See below.

What you saw

Just saying "it won't compile" or "it didn't work" is not useful. Doing this has been known to reduce the bravest, most patient developer to alternating fits of rage and tears. Please don't do this.

In all cases, please send the exact and complete output from the browser or the compiler or the runtime.

For web site problems, copy and paste the whole error mess from the browser into your mail program; don't just type one or two words from the screen.

On UNIX systems you can use redirection, or the script(1) program to capture a log of the errors. On other systems, or if you're using an Integrated Development Environment, you should be able to grab the results off your screen using copy and paste.

For Java programs, you should ensure that the code prints a stack trace if it catches any exceptions. See Java Cookbook Section 1.6, many code examples such as the code in Section 5.1, and Section 9.6 for capturing tracebacks from others' code.

What you think

If you have a theory, please include it (but mark it as such :-)).

Results

These steps will help you get a useful response. Depending on your support arrangements I will try to get back to you as soon as I can, but remember that free software that you aren't paying support on is a second priority to work that pays the bills!

See also Sun's notes on How to Write a Helpful Bug Report and Eric Raymond's Asking Smart Questions.

DarwinSys - Java Cookbook - Contact Form

On Development Platforms

Often people write in with problems saying that they can't find this or that class in one of the Java programs they have downloaded. While I understand that many people are committed to using Microsoft Windows as their desktop operating system, I submit that MS-Windows is an incredibly poor choice for a software developer due to its amazing paucity of simple development tools. I further submit that the UNIX operating system, having been in continuous use by practicing professional developers for over thirty years, has the best-refined toolset.

For example, if you want to find where an apparently-missing Java class is defined, instead of reaching for the mouse and rummaging about in some menus, you can simply say

grep SomeClass *.java

And you get your answer in seconds, not minutes. And those minutes add up. There are many other powerful UNIX tools that are part of the solution to programmer productivity, but they just aren't included in MS-Windows.

There are several very good versions of UNIX that you can download for free over the Internet; these come with source code so you can see how they work. Check out OpenBSD and Linux. Both have a desktop layer called KDE which makes a good transition from the MS-Windows environment due to very similar GUI presentation.