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.