The issue was first discovered by one of our users and submitted as a bug report. Let me first emphasize that this is clearly a bug in our DrJava code base, not in the submitted sample:

Note in particular that the closing brace is missing, so we would expect something like “} expected” or “reached end of file while parsing”. The user noticed, however, that when he compiled the following file with Java 6, he got an internal DrJava error instead.

The problem is that we are using String messages to pass the compiler errors and exceptions thrown in the compiler, and then we try to separate these two categories again: Compiler errors are displayed in the “Compiler Output” pane, exceptions are reported as an error in the “DrJava Errors” window.

How did we decide to distinguish errors and exceptions? Using a very unstructured string comparison:

If the word “CompilerError” occurs in the error message, it is treated as exception. Since the position of the “CompilerError” substring isn’t restricted, any silly compiler error in a file named CompilerError.java, or CompilerErrorModel.java, or CompilerErrorModelTest.java, or CompilerErrorPanel.java — all of which exist in the DrJava code base! — will be treated as serious unexpected exception in the compiler.

It is a really bad idea to use common words that could occur in user-generated text, like file names, as a marker for error conditions.

The solution for this problem, of course, was to analyze the structure of the error messages more closely: The class name of the exception, fully qualified as sun.tools.java.CompilerError had to appear as part of the string "Compile exception: sun.tools.java.CompilerError" at the beginning of the message. Spaces are not allowed in Java class names, so this cannot clash with a user generated file name. I changed the conditional above to:

Two additional lessons to be learned from this are that we need to run our tests with both Java 5 and Java 6, and that we need to eat our dog food even more: We should compile DrJava inside DrJava.

Fixed as of revision 5105. I have made a new jar available: drjava-weekly-20091006-r5105.jar.

Then there is a completely different category: Bug reports filed by users who are so unbelievably ignorant that they report a bug in a "Hello World"-level program of theirs as a bug in DrJava. That really makes me lose my cool.

In order to vent a little, I herewith present you the dumbest DrJava bug report yet: [ 1914390 ] Unhandled exception: java.lang.NullPointerException.

Check out this masterpiece of software engineering:

It’s difficult to put the null value and the method call any closer together. Truly stunning.

What I’m planning to do now is display a better error message, and ask the user if he wants to overwrite the files even though they are read-only. Generally, this transfers to failed attempts to save. Here, I want to present the user with a list of files that could not be saved and ask the user if he wants to retry saving them. For read-only files, there is a clear solution available: make the files writable (even though Sun, in their inexplicable enterprise to keep Java development challenging and interesting has provided the File.setReadOnly() method, but no method to make a file writable). For writes that failed for other reasons, there is no clear panacea, but a “Retry” option seems useful.

There already was a dialog that does much of what I need, ScrollableListDialog. It has been used to display a list of files that could not be found and have therefore been removed from the project. Now I’m going to extend that dialog so it supports more than just one button (“OK”), lets the programmer know which button was pressed, and let the user select files in the list. So it’s getting a bit more complicated.

When I looked at the constructor, I decided that it was already way too complicated. It was badly designed and as a result error-prone and time-consuming to deal with. Here is the main constructor of the class:

There were additional constructors that supplied default values so that not all values had to be set manually. Still, extending this structure even further meant adding even more constructors. I decided this was the wrong path. Instead, I chose the Builder design pattern.

The constructor for ScrollableListDialog is private, so instances cannot be created directly. Instead, there is a static class ScrollableListDialog.Builder that starts out with the default values in its fields. Builder has setters to change these values, and a factory method ScrollableListDialog build() that creates the ScrollableListDialog so configured. All of the setters return this, so setting different values can be chained together. Consider this explicit constructor call (using one of the other constructors that I haven’t shown):

This isn’t even the full-blown constructor shown above, but it already isn’t clear which of the strings is the title and which the text for the dialog body. If we add width and height, it isn’t clear which comes first. Type systems do not help here. Using the Builder pattern, the above becomes a bit more verbose, but much clearer:

Not only is this type-safe, but it also pairs up the value being set with its name. Using the Builder pattern, Java can achieve something similar to named variables, where the name of the variable has to be stated when passing an argument. The order in which the values are set is arbitrary, and only those values need to be bothered with that are actually important in the specific situation.

I should mention two little issues: First, some people may ask why everything in the Builder class can’t be static. Then I would not have to new the builder class and create another object. In single-threaded code, that would be fine, but if the Builder class is accessed from two different threads simultaneously, their settings would interfere with each other. Second, the builder pattern makes it slightly harder to subclass ScrollableListDialog: In addition to subclassing that class, the Builder class has to be subclassed as well so that it actually builds an instance of the new subclass.

Now that the Builder is in place, I can easily extend ScrollableListDialog without having to worry that other users do not know what to pass in for the canSelect flag, for example.

The subsystem is too big to completely show here on the Code Pranger, but I found instructions on what must be done to add a property to the project file:

So let’s see: If you are only adding some more data that describes a document, you just have to change three classes, and one method. That’s not true at all. You have to change the OpenDefinitionsDocument class, the inner classes ConcreteOpenDefDoc in both AbstractGlobalModel and DefaultGlobalModel, and perhaps one or more of the interfaces it implements as well, for instance INavigatorItem.

And if the data you are storing is of some new form, in a format for which we have no visitors (sub-parsers), then you have to write your own visitors. For example, for a list of breakpoints, I had to write this very short snippet, just to parse¹:

And when the data that you want to add does not pertain to one particular document, but is rather a property of the entire project, then you need to change ProjectFileIR, ProjectFileIRImpl and ProjectFileBuilder. At least that’s what the description says. But you’ll also have to change the AbstractGlobalModel, its subclass DefaultGlobalModel, perhaps one or more of its superclasses or implemented interfaces, and definitely also the inner class ProjectFileGroupingState in AbstractGlobalModel. And since we want to be able to treat both project mode and flat-file mode the same, you then modify the interface ProjectFileGroupingState is implementing, and that forces you to change the inner class FlatFileGroupingState in AbstractGlobalModel as well. Oh, and of course you may have the parsing problem again and have to write that lil’ bit of code up there again.

Once you’ve done all that, you finally get to the easy part of adding GUI components to the “Project Properties” dialog. I hate GUI work, but after the ordeal described above, it felt like a vacation.

I’m the only developer that has added² anything to the project file format during the last three years and eight months. I’m the only one who had to go through this pain since July 2004. In fact, I have suffered more than the person who initially created this complex construct, because after it was in place, only three small pieces of data were added, and then the project file format remained unchanged for a year and eight months, until I came along.

I have since added persistent breakpoints and watches from the debugger to the project file, persistent bookmarks and information about where the project’s jar file should be created, and using which options. I can’t exactly tell who came up with this code that has tortured me for hours because the SourceForge repository history doesn’t reach far enough back, and I wouldn’t mention the name here anyway, but it must have been written by someone who completely misunderstood fundamental principles of object-oriented design. The code is generally rather well written, assuming that nothing changes: It is correct and robust. However, the developer paid no attention at all to extensibility and flexibility, and made it a nightmare to extend the system.

This is a clear example of over-engineering, of thinking of doing it “the right way”, of creating a large object-oriented design that incorporates nearly all design patterns the developer partially understands. This is an example of code that made the original developer feel good about himself, because he came up with something he considered “pretty”, even though something much simpler and much less pretty would have sufficed, and in the long term prevented a lot of silent anger and premature aging.

Of course my XMLConfig class has about 600 lines of code and 500 lines of unit tests, and it relies on Java’s classes for dealing with XML files, but there’s no reason to reinvent the wheel. In fact, writing an S-expression parser for the project files is another mark of a bad developer who overestimates himself: Instead of looking around and using code that already exists and that has been tested, the macho programmer decides he can do better and without any reason writes the code himself all over again. And because this programmer isn’t as good as he thinks he is, and because he is human, he makes mistakes. The repository history shows several commits that had to fix bugs in the project file code.

XMLConfig is actually very simple code. It just takes a string, which describes a path, follows that path into the AST defined by the XML file, and then returns the value found at the end of the path. And once I got past writing and testing XMLConfig, which did not take long, I have been using it in almost every project that needs to save data. Instead of requiring code like the 80-line extract above, my code using XMLConfig can load a list of file names in a single line.

Soon, two of our current DrJava developers taking the COMP 312 “Production Programming” course will add a complex data structure to the project file, and I don’t want them to go through what I had to go through. I don’t want them to write something like the 80 lines above. And I want to get to a point where adding information to the project file is really easy, because right now the current project file subsystem acts as a huge deterrent against any kind of change.

1. Please don’t criticize the coding style. I wrote this code, but I mimicked the style the project file subsystem was written in. [back]
2. One developer changed the format slightly by changing the name of a property. [back]

To clarify, a pranger is a medieval device for torture and public humiliation, similar to stocks. Someone who had done something shameful was locked up in a pranger, usually by restraining the neck and both hands between two pieces of metal or wood, and exposed to the public. I am not going to expose the writers of bad code here (even though sometimes I might want to; let this be a reminder to myself: don’t!), I’ll just put pieces of code, which I find ugly, on the pranger.

The purpose, of course, is to provide anti-patterns, perhaps create some discussion, and increase the overall quality of code being written. I realize that I will probably won’t achieve the last of those goals. I also realize that I probably won’t even fix the examples of bad code, because I believe in the maxim of “don’t fix what’s not broken”, where broken and ugly aren’t the same thing.

Anyway, here we go. I absolutely hate this piece of code summarized below:

The method \_workDirectoryPanel() mutates the _workDirSelector field and returns the new value of the field at the same time. At the call site, the return value is used for further processing.

Why mutate and return? Either mutate the field, let the method be void, and use the field. It’s been mutated, so it’s ready to go. Or don’t touch the field, don’t mutate, return the new value to the caller, and let the caller decide what to do: Mutating the field, for example. If you really want to do both, at least return the old value of the field before it was mutated. That makes at least sense in some situations.

But mutating and returning the value of the field? That’s just a function with an ugly, perverse side effect. I really don’t see the use at all. Is it convenience? No, it can’t be, it would be more convenient just to mutate and not create the local variable wdPanel. Why would anyone write this?

I think mutation should be avoided whenever possible. Of course, in most production programming languages, that’s not possible. So make a void function and be explicit about the mutation you’re doing. There’s a programming style that really dislikes void methods; I sometimes subscribe to it. If a method is void, you can’t chain method calls together. If it returns something, you can. So if, for example, you have a List<T> class and the add(T element) method mutates the internal state of the list, then you could let the method return this:

That way, you can quite succinctly write something like myList.add(1).add(2).add(3);. But that’s a completely different situation.

Can anyone find an explanation why a method should mutate a field and return the new value of the field? I can’t.