Case in point: On a project where we were upgrading a system from Java 1.4 to Java 5, I happened to be the first developer to check in code with Java 5 type safety notation (which uses angle brackets) in a file that happened to be processed by a Hibernate 2 Xdoclet parser during the build process (if necessary). I didn’t realize that the Xdoclet parser didn’t know how to handle those angle brackets. Furthermore, I didn’t notice the problem because of the way the Ant script was set up, it didn’t manifest until after running a CLEAN task, but I had no reason to run CLEAN (just BUILD). So, instead, an unsuspecting developer on the East Coast was made to suffer, puzzling over the problem until I came online three hours later and realized what had happened.

So, in my experience, code generators seem to be much more successful when used as tools that are invoked on demand by the developers. The key distinction is whether or not the generated code is committed to version control. Looking back over the last seven projects that I’ve been involved with that made heavy use of code generators, three of them did so with post-commit generation. The four projects that used on-demand generation always seems to work out much better. On-demand generation simplifies much:

1. The build process is faster and more direct, with less to go wrong at build time, which is beyond the control of the committing developer. This is especially important when automating the build process to be unattended, with tools like Cruise Control.
2. Newbie developers do not need to be aware of the existence of the code-generation tools at all (until their first assignment that requires one). That’s less to go wrong when setting up a new development environment.
3. Exceptions to the rule can be handled manually. No need to spend hours perfecting rickety RegEx replacement tasks in Ant. (By all means, utilize RegEx replacement tasks when it is cost effective to spend the time writing them, but this way you get to choose when that is, rather than being forced into it. Also, this way it won’t kill you if the transform is not perfect.)
4. There is high visibility of the generated code. What’s checked in to version control is what you get. The exact changes are logged and can be easily differenced/compared/branched/tagged, just like any other code. There’s no question as to what the compiler is “really” going to compile and deploy.
5. By putting the developer in the loop between the code generation and the commit, it gives Eclipse a chance to chime in about errors and warnings.
   Also, if Eclipse can see the generated code, that means that all the power and might of the searching, navigating, and refactoring tools come into play.
6. When the code generators make bad decisions (e.g. when presented with a new kind of input), the results are more easily noticed because the developer facing the problem is the one who just did the on-demand code generation. Chances are, the problem will manifest as a blatant error, warning, or hint, or as unit test failure. Even if not, the committing developer might catch it still if he/she is disciplined in comparing the differences of every single file that he/she is about to check in (a good practice anyway for catching things like typos, unaddressed TODO’s, and extraneous debugging logic).
7. It’s easer for developers to mix and match tools, applying them in any arbitrary order, as opposed to the ones that are programmed in to the build process always having to be last.

I admit there are some downsides:

1. Having to make sure the developers know when and how they are supposed to use the tools, at the risk of them thinking they need to do the work by hand.
2. Remembering to revisit previously generated code whenever a code generator process changes, and either manually affecting the changes, or regenerating that code and merging back in any modifications that were done by hand. (Fortunately tools like WinMerge and Beyond Compare make this easier.)

There are undoubtedly more cons (as well as pros), but I’m convinced that the cons are easily managed and that the “low road” is the easier route.

One trick to filtering out the noise is to define a shell script that uses Rsync to create/update a searchable shadow copy of the working folder, and then to search that copy… In case you’re not familiar with Rsync, it is a tool intended to keep two remote file systems synchronized. Rsync’s main claim to fame is that it’s fast because it only transmits the differences, but Rsync is also quite powerful when it comes to specifying exactly which files and folders are to be synchronized and how. It’s this secondary feature of Rsync that allows us to filter out the noise. There are two parts to this solution: the actual shell script, and a file that lists all of the inclusion and exclusion patterns. (This example uses CygWin, running on a Windows box.)

Here is the (entire) shell script (C:workcmdsearchcopy.sh):

 #!/bin/sh
 pushd /cygdrive/c/work
 mkdir -p /cygdrive/e/work_search
 rsync -vrut --filter='. /cygdrive/c/work/cmd/searchcopy_filelist.txt' alpha bravo charlie /cygdrive/e/work_search
 popd

• /cygdrive/c/work is your working folder (that’s CygWin speak for C:work).
• Alpha, bravo, and charlie are the folder names of the projects that you are interested in.
• /cygdrive/e/work_search is the name of the searchable shadow copy you want to create/update (over on your E: removable USB drive).

Here is (an abbreviated version of) the filter file (C:workcmdsearchcopy_filelist.txt), to give you an idea:

 - .svn/
 - bin/
 - build*/
 - deployment/
 - lib/
 - log/
 - .#*
 - *.[ehjstw]ar
 - *.[Bb][Aa][Kk]
 - *.doc
 - *.[Ee][Xx][Ee]
 - *.gif
 - *.httpunit
 - *.ico
 - *.jasper
 - *.jpg
 - *.library
 - *.log
 - *.[Oo][Ll][Dd]
 - *.pdf
 - *.[Zz][Ii][Pp]

In this case, they are all exclusions (leading minus sign), Thus, everything in the alpha, bravo, and charlie folders will be copied, except files or subfolders matching these patterns.

Tips for using Rsync:

• Don’t waste time with the –include and –exclude switches, they are merely dumbed-down versions of the –filter switch, so just use the –filter switch right off.
• Avoid the –cvs-exclude switch, if you can, and pay close attention to what it ignores if you can’t. For example, it ignores any file or folder named “core”, and it ignores *.script files; both of which burned me when I tried using it on a certtain Tapestry application.
• Most implementations of Rsync are case sensitive, including CygWin’s! So if there is a possibility of filenames that exist with multiple casings, then you either have to repeat the pattern or use the square bracket notation:

   - *.EXE
   - *.Exe
   - *.exe

  or

   - *.[Ee][Xx][Ee]

• Pay close attention to the man pages that describe other aspects of the pattern matching algorithm. For example, leading and trailing slashes each have special significance.

I’m helping out with a study group for “Head First Design Patterns,” which just finished chapter 6. On the whole, it’s a pretty good introduction to software design patterns — way more accessible than the seminal work by the Gang of Four; however, the examples sometimes make my head hurt. I can’t imagine what they’re doing to the heads of the beginners in the group. Coming up with decent examples is the hardest thing to do in expository writing, and I certainly give the authors an E for effort in creativity, but I wish they had been a little less concerned with making their examples “hip” and a little more concerned with making them appropriate.

To wit, the whole pizza store analogy in chapter 4 (to illustrate factory method and abstract factory) is flawed. For one thing, that’s just not the way you’d model a pizza business in any actual software that I can imagine. For another, the differences between a New York pizza factory and a Chicago pizza factory are too subtle/trivial to make for an effective illustration of why you would need to subclass anything (much less use a factory to manage the subclasses). A much better example, as everyone in my group agreed, would have been an application that needs to offer up a consistent set of functionality to users who are accessing it in wildly different ways: one’s in a web browser on a desktop, another is running a cell phone app, another is using a touch-tone phone, and yet another is using a voice-activated headset. All the client code knows is that, for example, it needs to ask a multiple-choice question and obtain the answer. It’s up to an abstract factory to provide the client with a set of classes that can do that, in the context of the selected user-interface, in whatever way is necessary.

To a lesser degree, the Starbucks coffee example at the beginning of the book suffers from the same too-hip-to-be-effective syndrome, although I do think that the remote-control example for the Command pattern in chapter six is dead on.

For any novice who is reading this book without the benefit of a study group, I highly suggest that you find at least one other programmer who is experienced in design patterns to explain why/if/how the examples are lacking.