Top ten code-generation rules

Everyone can recognize me as a die-hard code-generation fan, with a twist: use a model as the starting point. I adopted the idea every week, practicing “dog fooding”, using my own code generation project AjGenesis. This week, I’m reading the now classic book “Code Generation in Action” , by Jack Herrington, edited by Manning. This book is a “must be read” to everyone interested in code generation. It’s a very interesting reading for developers, but also to managers: the author makes the case for use code generation, appealing to increasing quality and productivity, including agile teams.

In the first chapter, Herrington lists top ten rules I want to comment in this blog. The indented paragraphs are textual excerpts from the book (section 1.7), followed by my own comments:

Give the proper respect to hand-coding

You should both respect and loathe handwritten code. You should respect it because there are often special cases integrated into code that are overlooked with a cursory inspection. When replacing code you’ve written by hand, you need to make sure you have the special cases accounted for. You should loathe hand-code because engineering time is extremely valuable, and to waste it on repetitive tasks is nearly criminal. The goal of your generator should always be to optimize the organization’s most valuable assets—the creativity and enthusiasm of the engineering team.

Yes, the basis of code generation is to make easy to delegate the repetive tasks to the machine. We have to use tools that make easier our work: that’s the reason we are using compilers nowadays, instead of switching the bits directly in memory (or setting the relays in the old Eniac). Code generation rationale is not to destroy the handwritten code: its mission is to support it.

Handwrite the code first

You must fully understand your framework before generating code. Ideally, you should handwrite a significantly broad spectrum of code within the framework first and then use that code as the basis of the templates
for the generator.

Absolutely yes. Sometimes, new users of AjGenesis begin to use it directly from the examples. That is good, but it would be better to generate an example using the framework and technology they uses. If you know how to program using Struts/Hibernate, then, you can separate the variations from the essentials. At that point, you can begin to write the code generation artifacts (templates, tasks).

Control the source code

I can’t stress enough the importance of having a robust source-code control system. This is critical to a successful code-generation project. If your generator works directly on implementation files that contain some hand-written code, make sure you have a versioning system running that can protect your work.

Another path: if you generate the code from a model, check in only the model. The rest of the artifacts will come from code generation process. With the current technology, you can’t generate ALL the solution, but you can separate, with care, the generated part from the manual one.

Make a considered decision about the implementation language

The tools you use to build the generator do not have to be the same tools you use to write the application. The problem that the generator is trying to solve is completely different from the problem being solved by the application. For that reason, you should look at the generator as an independent project and pick your tools accordingly.

That is one of the reasons that supports my adoption of a new language (affectionately named AjBasic) for my code generation tool AjGenesis. I wanted a dynamic language under my control, to extend in any direction the code generation process requires. In one of my initial test, I tried PHP, but I prefer to have a dedicated language.

Integrate the generator into the development process

The generator is a tool to be used by engineers; thus, it should fit cleanly within their development process. If it is appropriate, it can integrate with the integrated development environment (IDE), or in the build process or check-in process.

Making the core of AjGenesis as a class library, it could be integrated to other tools. You can use from NAnt, for example. An IDE tool calling AjGenesis is a pending task.

Include warnings

Your generator should always place warnings around code that it generates so that people do not hand-tweak  the code. If they hand-tweak the code and rerun the generator, they will lose their revisions. In addition, your first response to people ignoring the warnings should be to help them and not to berate them. The fact that  they are using your tool is a big step. Learn why they needed to ignore the warnings and improve  the generator or the documentation. You are the emissary of your tool.

In AjGenesis, this issue is the concern of the templates the user writes. You can add any text you like: that’s the power of writting your own templates, you have the ownership of the generated code.

Make it friendly

Just because a generator is a tool for programmers doesn’t mean it gets to be rude. The generator should tell the engineer what it’s doing, and what files it has altered or created, and handle its errors with a reasonable amount of decorum. It may sound silly, but a tool that is difficult to use or that’s flaky will be ignored and your efforts will be wasted.

AjGenesis core is a dll, that can be invoked from any application. Years ago, I wrote tasks to use it from NAnt. Thanks to Jonathan Cisneros, we have now the AjGenesis Studio, since last year. I improved the original code at the beginning of 2008, adding AjGenesis Web Studio. The error handling must be improved, specially for new users of AjBasic.

Include documentation

Good documentation is a selling point for the generator. Your documentation should be thorough but not overwhelming, and should highlight the key points: what the generator does, how it is installed, how it is
run, and what files it affects.

Actually, is a point not very covered by AjGenesis. But in exchange, there are many blog posts explaning the process, ideas, and examples (AjGenesis posts) (AjGenesis posts in Spanish). Users of the tool are beginning to write too (read Carlos Marcelo Santos posts). There is an Spanish email list where the users can discuss the tool (Code Generation group). And in the Codeplex project page, there are examples for Java, .NET, and PHP, many of these using the same model (the litmus test).

Keep in mind that generation is a cultural issue

Educating your colleagues through documentation, seminars, and one-on-one meetings is critical to successfully deploying the generator. People are skeptical of new things, and a good programmer is twice as skeptical as the average person. You need to break through those concerns and doubts and emphasize that you designed the generator for their benefit.

I gave three to four speech by year, only dedicated to explain the tool and its potential. Additionaly, I explain the tool in every course I give (Java, .NET, PHP, or software development in general). But to be adopted in a company or project, a power user must became the champion of the tool. It’s not easy to raise the level of abstraction, write the model and its transformation, in the middle of the day to day work.

Maintain the generator

Unless the generator is just a temporary measure, it will need to be maintained long term. If the generator manages a large portion of code, treat it just as you would an engineer maintaining that same piece of code. Your budget should include dedicated time and money for maintaining and upgrading that resource.

AjGenesis is not the “things” to maintain. They are the templates and tasks you use in your work. If you adopt the tool to generate .NET applications, you have to change and improve the templates when new tech appears (LINQ, ASP.NET MVC….). And when you gain experience, you have to improve the model itself, if you discover new ways to represent the product lines your company are involved.

I could add some points more:

– The generated code generated must be the kind of code you are proud to write by yourself. The tools should not dictate the form and appearance of such code.

– The use of a model raise the level of abstraction. Such strategy separates the wheat from the chaff, put the technicalities in the place they deserve: the importance is in the model

Well, enough for now. As you can notice, code generation is one of the subject that passionate me. It’s not the silver bullet. But it is a bullet I want to have, just in case.

Angel “Java” Lopez
http://www.ajlopez.com/en