Generated Files

This section gives you some hints on how to efficiently work with generated files.

What to check in into a version control system

According to the generation gap pattern, generated code should never be manually changed and not be checked in. Although it is possible to use Virtual Devleoper to develop generators that create code that follows this pattern, we do not think it is the best way to go forward. Always checking in all files gives you some advantages:

  • you can check out the code and instantly use it, without having to generate anything
  • the directories in your software projects continue to follow conventions of your build tool, e.g. using src/main/java and src/test/java as source code directories for Java projects when you use Apache maven.
  • the structure of your source code remains the same as it would be without using code generation, e.g. no artifical inheritance relationships due to the generation gap pattern

Manual changes in generated code

Generators provide so-called developer areas in generated files. These are sections where developers can write code that will not be overwritten by the next generation run. When you use an IDE to work with generated code, you can easily use its search functionality to identify all developer areas that were manually changed.

Information about generators in generated files

Often it is desired to know which version of a generator has been used to write a file. In order to fulfill this desire, a generator should write its name/id and its version to the generated file, typically in a comment section. Here is an example of such an information:

/**
 * Generator: com.gs.gapp.vd-capability:1.0
 * Model: name=LayoutVariant, type=enumeration, module=DashboardViews
 */
public enum LayoutVariant { // start of class

...

Note

Only the major and minor versions of a generator are written to a file. Also writing the bugfix version number would lead to a big number of modified files for every time a bug fix version is released.

Many modified files after generation - what to do?

When you use newer versions of generators, it can easily occur that the generation results in many modified files in your workspace. And you are not sure what to do with them. Do you have to check all of them, in order to see which changes you would want to check in? The answer is: You could, but there is a better way to handle this:

  • First of all, you should know about a new generator version being available and being used. This is mainly a communication issue. Check a generator’s release notes in order to know beforehand what you have to expect.
  • Then, before running the new generator version for the very first time, you should check in any pending changes.
  • After having run the code generator, you shold normally always check in all changes. When you are unsure whether your latest coding work is still there after generation, simply do a file diff using your version control system.
  • Your automated unit and integration tests should fail when the new generator version has a bug or when you made changes that were overwritten by the generator. After the very first generation run with a new generator version, you can execute those tests on your development computer to get confidence about the quality of the code base.

Note

When your generator writes its name/id and its version to generated files, you will easily notice that you have just been using a new version of a generator. In this case All files will be changed after the very first generation with the new version.