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 version of the software are you using. Be specific:

If it's a Java Compilation problem:

If it's a Java runtime problem:

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 almost all systems with command-line capabilities, you can use "redirection" to capture a log of program output. On developer-friendly systems (UNIX/Linux/Mac OS X) you can use 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 textual log of 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 :-)).

If you want to send an update or bugfix to my software, please send it as a "git pull request" for the repos on, or send it as a diff(1) -u output against the current cvs version for the repos still in CVS. Thank you!


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! And by the way, please do not ever write in asking me for links to files that are on my public web site. You should instead learn to find stuff on your own instead of expecting others to spend their time doing it for you, for free. If this is a consulting gig, that's great; I live in Canada so I have to charge North American consulting rates.

Similar: Sun's notes on How to Write a Helpful Bug Report, Simon Tatham (author of putty ssh client) on How to Report Bugs, and Eric Raymond's Asking Smart Questions.

DarwinSys - Java Cookbook - Contact Form