tips for code generation

i am generating source code from xml-documents or other source code for years now. however, i learned some lessons over the time. these tips might be obvious to you, but i thought i should summarize them up:

1. don´t

you should really know where/if code generation is necessary. often code generation can be avoided by using clever frameworks, reflection and clean separation of responsiblities. if there is any chance to be successful without code generation, try it. code generation might seem to be elegant at first but has a significant number of disadvantages. (for complete argumentation see the fabulous wrox book: J2EE without EJB of spring creator Rod Johnson)
the speed of reflection today, together with JDK5 annotations are excellent tools to get rid of compile-time generated code.

2. automate

using IDEs to do code generation is not easy to automate. you should be able to generate your code while compiling instead of creating them once while coding.
you should definately avoid adding generated sources to your version control system for obvious reasons. if your code generation depends on you IDE (and manual intervention) you´ve just blown any chance for automated tests, continous integration etc.

3. generate code you can extend easily

create abstract classes and empty classes that extend them. when regenerating, only generate the abstract classes, so that overriding generated code is easy. remember to think about inheritance in a way so that you do not bind your generated classes to one base-class and make inheritance impossible. at least it should be possible to make the generated class extend any other class.

4. minimize generated code

if you go for code generation, avoid code that actually DOES many things. may sound odd at first, but be sure to refactor almost anything out, that does not necessarily depend on the information you have at creation-time. in essence: create glue-code only.

5. use existing tools

if you prefer to use annotations (and decide that runtime-code-generation is not an option) use or extend xdoclet or (if you really have to) use qdox for source parsing.

if you really have to reinvent this wheel, at least use one of the well-known template engines to prevent having out.println lines cluttering your code. (some options are: xslt, velocity, or eclipse´s jet-engine)

5. create version-control metadata

if using only one source tree, create/extend .cvsignore (if using CVS) and similar files to make sure generated code does NOT make it into your version control system.

6. use separate source tree

if possible use a different source tree for generated code. this helps a great deal maintaining because you can simply exclude it from version-control, coverage test, static code analysis.

7. mark it as generated

whatever you do, help the maintainance programmer to immediatly recognize this code as generated and re-generateable. separate source tree is great for that. additionaly use classnames like GeneratedAbstractXY and generate class header-comments that include at least the following:

• when it was generated
• from what it was generated
• a reference on how to regenerate

feel free to complete this list with your experiences.