Title: Automatically-Generated Nightmares

A student sent me the source code for a mini-project of his. It came to about 100 printed pages of Java code, and he had a problem with it. I started looking through the code, but it was very difficult: there were hardly any comments, and most variable names implied that the code was something to do with a graphical interface but it was hard to see exactly what was going on, and anyway the problem in question had nothing to do with the interface. I searched in vain for the part of the code that actually did something other than manipulating interface objects, and wondered how on earth he can write all of this without getting completely muddled. I thought "am I such a lousy programmer that I can only deal with small and manageable code while the new students can write reams and reams like this?" and "how many hours a week is a programmer expected to work these days to come up with all of this?" and "perhaps I'd better admit my utter lack of productivity now and find a different job". When I finally figured out roughly how it all worked, I asked the student a question about part of the code that I thought was more suspect than the rest, and his reply was "Oh, I don't know about that; the GUI wizard program wrote it all for me." Ah! So THAT'S why it was so big and complicated. I shouldn't have worried so much. Or should I?

There are plenty of "GUI wizards" and other tools that will generate code for you, and that code will usually contain "TODO" comments to show where you should add your own logic.

Unfortunately it seems that most programmers, after writing what they are prompted to write, delete the "TODO" comment and do not add another in its place, which means that anyone else who wants to browse or debug the code will first have to spend considerable time unravelling the automatically generated code to try and figure out where the user-written code is actually located. This must add up to an awful lot of wasted programmer time in the industry. While some tools give you code that is relatively easy to follow when finished, others generate such large amounts of hard-coded graphical widget handling that you'd be pushed to find anything else.

I can understand why programmers want to delete "TODO" comments, especially in the light of tools that flag them up as "things not done", but I think it would be better if, instead of deleting the whole comment, they simply delete the word "TODO" when they've done it. That would leave a comment that gives some description of what is happening and also serves to highlight where the user-written code is to be found; as the automatically generated parts usually have few if any comments, any comments at all would make your code stand out. Even a complete beginner who is not skilled at writing comments can adopt this method, and it would make things a great deal easier for anyone who has to check their work.

What would be even nicer is if more of the wizards and other rapid application development tools could promote a clearer separation of concerns between your code and their code. Object-oriented languages like Java support this naturally (think of encapsulation and all the other buzzwords you know) but it's not being used as well as it could be. Why do the tools promote obfuscation, turning Java into a language of a much lower level than it was designed to be?

Perhaps it is because they want you to spend a lot of money on other tools to help you maintain the code. In effect, they are creating a language of their own which gets compiled into Java and then has to be de-compiled by their tools before it makes sense. Java is going the same way as HTML: it was originally intended to be written and read by humans, but now most of it is generated automatically and can't easily be made sense of without highly complex tools (and even then you're not guaranteed to see the programmer's intentions). To see what I mean, take a straightforward text editor and try to make sense of the source code in an average Eclipse plugin. (Yes I know some of them are better than others.)

The problem is that the tools are not always available. What if you want to review some code when you don't happen to be sitting at your most powerful computer? When you're not at any computer? When the tool doesn't co-operate with your special disability access software, or its layout is too complex for the size of the display you're using? When there are license restrictions that get in the way of your using it in the circumstances at hand? When you don't even know what tool you're supposed to be using because someone has handed you the code without telling you? It's understandable that you need the right tools when compiling or testing code, but it's rather more restrictive if you have to arrange your life around them just to look.

Moreover, what if the way that you think best when you review code does not tie in with the way the tool pushes you into thinking? Sometimes tool designers push you into a particular way of thinking for a good reason, but at other times they're just being short-sighted. It reminds me of Green's Cognitive Dimensions of Notations theory; ordinary text editors and printouts, when applied to code that is designed for them, tend to be good at allowing "viability" of the notation, avoiding the need for "premature commitment", and so on, whereas other tools don't always do so well. While they may make some developers more effective, others become less effective, and that's bad news when you're collaborating.

If you are a user of a code-generation tool, perhaps it would be a good idea if you put your own code in a completely different file, and get the automatically-generated stubs to call it. This should make it easier when the code needs reviewing, or when you want to reuse parts of it in other projects. It also makes it easier if for some reason you want to re-run the tool, or to run some other tool (perhaps for a newer kind of interface) without throwing away all of your work. If you can't do such separation, then at least keep clear comments about which parts of the code were written by hand, otherwise you may be in trouble later.

Unfortunately, for the project in question, we ended up starting over, because I thought that this would be less effort than trying to figure things out from the forest of automatically-generated code that was camouflaging the parts of interest. It shouldn't have been that way.