• Capturing the application semantics at the abstract level can aid in the develop-
ment of work products outside implementation code. These can include vari-
ous forms of documentation, test cases, product support materials, and so forth.
• High morale—Long projects can be tough on teams, and long projects with
large amounts of tedious coding can be even worse. Code generation reduces
project schedules and keeps the engineers focused on the interesting, unique
work, as opposed to grinding through large volumes of tedious code. In addi-
tion, because the quality of generated code is uniformly high, the engineering
team will have confidence and pride in the code base.
• Agile development—A key feature of generated code bases is their malleability.
We discussed this topic at a technical level earlier; at the business level, this
means that the software will be easier to change and upgrade over the long run.
In upcoming chapters, we discuss the development lifecycle and how to build a gen-
erator. In this section, we provide a roadmap for the development and deployment of
a generator within the engineering organization.
The sections that follow outline the entire lifecycle of the generator—from assess-
ing the need, to development, to maintenance.
Assessing the need
The first step in getting help is admitting you have a problem. So it is with code gen-
eration. You first need to see the problem you have at hand and then decide if
code generation is the right solution to that problem.
In the case study, the first clue that we needed a code generation solution was the
schedule impact of writing 1,050 Java files. The second clue was the monotony of the
task of writing the Java code. Both of these are strong indicators for using code gen-
eration. If you need a lot of Java files, and writing them is monotonous work, you will
want to generate those files.
Once you have assessed the need, you must decide for yourself how you want
to present the case to engineering and management. You can choose from three
basic strategies: the formal method, the Skunkworks method, and the “my own
The formal method
This method involves turning the generator into a full-fledged project from the
beginning and following whatever process your company has for the design and
implementation of software engineering projects.
The first phase of software design is the requirements phase, in which you gather
information about what the generator needs to do. In this phase, you want to agree
on the scope of the work handled by the generator. In particular, you must clarify
• How much will the generator do in the first release? The scope should be very
clear on this issue.
• How much will the generator do in the subsequent releases? This will help
define the long-term architecture of the generator.
• For what is the generator responsible? Having clear lines of responsibility will
allow you to ensure that key features are implemented and that extraneous fea-
tures are left out.
• For what is the generator not responsible? Going through the exercise of catalog-
ing what a piece of software is and is not responsible for is very valuable.
• From an outside perspective, is there anything unusual about what it covers or
does not cover? Make sure you catalog the areas of responsibility that could be
considered unusual to someone just coming into the project.
In addition to clarifying the scope of the project, make sure you establish some basic
goals about the development process for the generator. Here are some points you may
want to clarify:
• How will the generator fit into the development cycle?
• Will the generator go to the customer or stay in-house?
• What style of generation will it use? It’s important to get a consensus on what
type of generator to build. This book will present many types of generators as
we go along.
• How and when will an engineer use the generator?
• Is it a permanent or temporary solution?
• Who will maintain the generator?
• Who is the arbiter of features for the generator?
• Is the first release of the generator prototype code or production code?
• What development tools will be used?
These types of questions have to be answered in addition to the standard feature
The advantage of the formal method is that if the project goes forward, it has every-
one’s blessing. The disadvantage is that the generator project may fail through bad
project management, or by having too many features, or by having too little clarity
around the feature set.
The Skunkworks method
The term Skunkworks is used when an engineer goes off on her own time and imple-
ments a solution and then returns with it to the team. At this point the question of
deployment and maintenance becomes an issue for the team to resolve.
The value of this technique is the elimination of all external influences from the
process. You think up the project and then build it. If the generator project fails, then
nobody knows but you.
Of course, the disadvantage is that you can frighten or alienate other engineers
or managers, and you may lose your work if they decide not to use your generator.
The “my own tool” method
The directive comes down on high that all your methods must now have X by next
week to conform to the new architectural standard. What do you do? You can either
get typing, or you can make a tool to do the work for you. This is the type of scenario
that breeds the “my own tool” generator.
The my-own-tool method is the same as the Skunkworks model except that, at the
end, the tool remains yours. You don’t present it to the team, because they might say
it shouldn’t be used. As long as the tool is yours, you can use it as you wish, and
nobody will be the wiser.
You may find that you have a perception problem if people find out. It’s not good
being “that nut with that tool nobody understands.”
That being said, there is nothing stopping the my-own-tool generator from
becoming a Skunkworks generator or being promoted to a formal method generator.
All you need to do is tell people about it and do a little educating.
Laying down the infrastructure
After figuring out what problem you are solving and how you are going to solve it,
the next step is to get your tools ready. This process involves several steps. The most
important is to control and track versioning across the development team. You will
also need to set up a test environment, select the full suite of tools that your team will
use, and communicate those choices clearly.
Ensure source-code control
Source-code control is so important that I will mention it many times. Source-code
control is vital when working with code generators because large blocks of code are
rewritten in the blink of an eye.
Make sure that you are familiar with the command-line interface of your source-
code control system. Also, be familiar with any check-in or checkout automation facil-
ity the system may have. Using the automation facility may be an easy way to integrate
your generator into the development workflow. For example, you could have your
documentation generator automatically build documentation upon source code
You should also check the Internet to see if a wrapper is available for your source-
code control system. Perforce, for example, has Perl modules on CPAN that give you
access to all of the Perforce functionality through convenient Perl functions.
Build your sandbox
You should use your source-code control system to build a sandbox for the generator
and the code it creates—particularly when integrating a generator into an existing
system to replace existing code. This allows you to run and test the generator in
isolation without worrying about corrupting the main branch and interrupting
anyone else’s work.
Standardize your development tools
If you are using different development tools for the generator than you are for the
application, you will want to spend a little time preparing those tools for deploy-
ment. In particular, you should take the time to create an installation kit with just the
executables and extra modules required to support the generator. Be sure to docu-
ment the installation procedure; nothing kills the enthusiasm of an engineering tool
deployment quite like installation problems.
This also means locking in the version of the development tool you use. You
should look at the versioning of these tools with the same skepticism that you would
an update to your C, C++, or Java compiler. Each compiler, interpreter, or plug-in
module you use should be frozen at the deployment version and then upgraded
Buy it or build it
At this point, you’ve laid the groundwork for the development. Now you need to
decide whether to buy or build the generator.
Buying a generator is not the end of the game; it is just the beginning. First, you
must test and customize the generator against the code you would like to build.
Remember, the generator is just a tool. Because you must assume complete responsi-
bility for the code that it generates in production, you should feel completely confi-
dent about the behavior of the generator and the code that it creates. Also, standardize
the installation of the base package and any customizations that you have made—just
as you would with any development tool you use.
The emphasis of this book is on building generators. This approach provides you
with full control and also allows you to understand what an off-the-shelf generator is
doing for you.
Once the generator is finished with its first release, you should concentrate on docu-
mentation. You have to create this documentation regardless of whether you buy or
build the generator.
Two basic forms of documentation go along with the generator. The first is the
architectural document and will be used by the maintainers of the generator. This doc-
ument should include:
• The design goal of the generator
• Pros and cons of the generator approach as it applies to the problem at hand
• The block architecture diagram for the generator (see figure 1.5 for example)
• Information about the tools used (e.g., versions, links, installation guidelines,
• The directory organization
• The format of any input files
• The purpose of every file associated with the generator
• The unit test process
• The installer build process
• Information required to explain the special cases covered by the generator
• Behaviors of the generator that would not be apparent at first glance to some-
one unfamiliar with the generator
• Contact information for the current maintainers
• Known bugs
The second document is aimed at the end user. It describes how the system is to be
used and should address the following:
• What the generator does and does not do
• Installing the generator
• Testing the installation
• Running the generator
• Deciding who should run it
• Determining when it should be run
You should also include:
• A warning about altering the output of the generator by hand
• A graphic that shows the input and output files and the flow of the generation
Documents you may be interested
Documents you may be interested