How to write useful error messages

Each programmer has to deal with error mesages in some way. Either we have to check our data (and possibly raise an error/exception) or we are using libraries and have to deal with error messages or exceptions that are raised in these libraries. The purpose of this post is to point out how meaningfull error messages can save you time. Either your own time (by avoiding answering support questions) or your own debugging time.

So how can an error message save or waste time? Imagine the situation where you try to open a file and all you get is an error. What do you do next? I guess you’ll probably check if you’re trying to open the correct path. Maybe you did, then you possibly check if the permissions are okay, if you’re trying to open a directory or a file, etc until you found the problem that is causing the error. Actually this can be quite some wasted time – why? Becasue you’re doing all the stuff that the system already checked. The system decided that one of the condidtions failed and exited. So – shouldn’t the system just TELL the exact reason? And even better: shouldn’t it also just tell you a possible solution? Well – actually I do not blame “the system” but the guy who write the line that threw the error without any further information. Everytime I get an absolutely uninformative error I think “was it really so damn hard to add one more line of code that just mentions WHAT went wrong?!”.

Assume the situation where you try to open a file with the path being configured in an external config.properties file.
I think the quality of an error message can be categorized in one of the three categories:

  1. Reporting: The system just reports that there was an error.
    Example: IO Exception occured.
  2. Informing: Same as 1, just with more information.
    Example:  IO Exception occured while opening file: <filename>, null=false, exists=true, is file=false, is directory=false, readable=false, writable=false
  3. Supporting: same as 2 with additional information of how to solve the problem.
    Example: IO Exception occured while opening file: <filename>, null=false, exists=true, is file=false, is directory=true, readable=false, writable=false; Was the pat set correctly in config.properties?

In the past weeks I have seen very useful error messages in Google’s Android (“… Have you declared this activity in your AndroidManifest.xml?”) or in twitter4j (Displaying a shortURL to an FAQ page explaingin a very common error).
Bad examples are plain NullPointerExceptions when 3 parameters were checked, one of them was null and the according is just followed by a throw new NullPointerException so that you even did not recognize from the message WHICH parameter was null.

Conclusion: Please write robust code and please provide helpful and supportive error messages to the folks using your code!

Parse Error: There is a problem parsing the package / Beim Parsen des Pakets ist ein Problem aufgetreten

Just finished my first (real) Android App and wanted to deploy it in my phone (not just in the emulator).
So I sent an email to myself with the .apk attached as several tutorials said that you can just open it from your mail to install the app.
On the phone, I opened my mail app K9 and opened the .apk. But instead of installing I unfortunately just got

Beim Parsen des Pakets ist ein Problem aufgetreten.
(in english) Parse Error: There is a problem parsing the package.

even though the minSdkVersion was set correctly.

The solution was rather simple: Do NOT open the .apk in K9 directly but save it to the sdcard and open it via a filemanager like Astro.

Linking API and Sources to your IDE’s JARs (Part 2)

I tend to upload my complete project into version control. This includes the sources, tests, Jars and also the nbproject directory where NetBeans stores the project configuration. By doing so, I can check out the project on a different machine and start quickly without having to configure the project.

Sources and API Docs of external libraries are not commited as they’re are not requried for compiling. I usually keep sources and docs in a separate place outside my project (let’s say <userdir>javaLibs...).

When I check out the project on a different machine I can do coding but I do have neither the sources nor the API docs. Even worse: as I’ve commited the whole project including the configuration, I have also commited the nbproject/project.properties file which stores the pathes to the source and docs. Which is not a problem if the pathes on all the machines are the same. But when a new contributer wants to join in, (s)he either has to use the same directory structure (and possibly the same OS) or he has to overwrite the settings. Both not very desirable.

Continue reading Linking API and Sources to your IDE’s JARs (Part 2)

Linking API and Sources to your IDE’s JARs

For productive programming, I think it is absolutely crucial to also have both the API documentation and the source code of the according libraries available and integrated in the IDE in order to gain maximum productivity. Integrating the API and sources is pretty easy in NetBeans (as well as in other IDEs):

Right click the Project > Properties > Libraries > select the JAR for which you want to link source and API and hit the edit button on the right.
Now you can select a folder, Zip file or Jar file for the API and sources, hit OK and you’re done.

Whenever you’re using a class from this library, you now can step into this class (by Ctrl-Clicking for example) or quickly jump to the API by pressing ALT+F1 when the curser is at the corresponding class/method.

If you are annoyed by swithing between IDE and Browser or if you just forget the Alt+F1 key combo that opens the browser with the correct API page, just enable the NetBeans inline Java-Doc viewer by selecting:
Window > Other > JavaDoc
This brings up a new panel which shows the JavaDoc comment of the class/method which is curently selected by the cursor. And you don’t even need to press any key for updating the view as it is updated automatically.

If it doesn’t work, I usually experience the following two errors:

  1. JavaDoc doesn’t work: If I perform Alt+F1, the browser doesn’t open and the status bar on the bottom of the NetBeans window shoes a “Cannot perform Show Javadoc here”. Well – check the Path then. It should end in a directory that also contains the index.html, package-list, allclasses-frame.html etc.
  2. The source is not displayed – even though the path to the Jar/Zip is correct! In that case, The Zip/Jar often contains all the source code in src/mypackage/foo.java. NB expects only packagis in the Zip, so that the content list should look like: maypackage/foo.java. So simply build another src.zip with the contents of “src/” (in this case) and you’re done.