13

One of my colleagues likes to use automatic code generators, which create large amounts of code that is poorly documented and very hard to maintain.

Is the cost of using a code generator worth the hassle in maintenance, for the reduced time to creation?

Maniero
  • 10,826
  • 14
  • 80
  • 133
Mumbles
  • 469
  • 1
  • 6
  • 16

4 Answers4

23

Code generated by a generator should never be maintained by hand. If it needs to be changed, then the generator and/or its settings must be tweaked and run again. Considering that, it doesn't matter if the resulting code is incomprehensible and undocumented as long as the generation mechanism itself is crystal clear. (Be sure to document the fact that the code is generated, and where the generator is and how it works.)

Analogy: while my computer's processor is always executing machine code, I don't need to know anything about it as long as I know how to create that machine code using high-level language and compiler. I've heard that GCC sometimes produces subpar machine code, but who cares, as long as it works perfectly. Database abstraction layers produce SQL to operate with the DB engine, but who cares what that SQL looks like, as long as the abstraction layer is clear and works?

When properly used, code generators can definitely save not only creation, but also maintenance cost.

Joonas Pulakka
  • 23,534
  • 9
  • 64
  • 93
  • 4
    The problem then become, only one person has the tool, no one else does, and therefore has to manually maintain the code. – Mumbles Oct 04 '10 at 15:44
  • This is passing the buck. As software developers, our business is code - no matter how we produce it. – Steven Evers Oct 04 '10 at 16:13
  • 12
    @David, if only one person has the tool, you shouldn't be using it for a project involving more than one person. – Matt Olenik Oct 04 '10 at 16:25
  • 2
    @Matt, exactly. Generators are part of the project (comparable to build scripts) and should be stored in version control or similar central repository. – Joonas Pulakka Oct 04 '10 at 17:17
  • 2
    @SnOrfus: I think our business is to produce working products that people are willing to use and buy. That's where our salary comes from. Code is just a medium. – Joonas Pulakka Oct 04 '10 at 17:26
  • Agree 100%, code generated by a generator is an artifact, no-one should be maintaining the artifacts of a project, only the source files (be it code, build scripts or whatever). Generated code should never be edited by hand, IMHO. – FinnNk Oct 04 '10 at 18:51
11

Let's rephrase that:

Is the cost of a good automatic code generator worth it?

Yes.

Is the cost of a poor automatic code generator which creates more work for everyone else but it's author worth it?

Absolutely not. There is no excuse for poor code. If someone wants to be clever and use automatic code generation then they should take the time to ensure that the code generated is good code. Otherwise, what's the point of it? It's only pushing the buck down the rode and when it comes to code production, the buck should stop at the developer who wrote it.

wheaties
  • 3,584
  • 22
  • 23
  • 17
    I disagree with your second point. The generated code only needs to be **good enough** so that it works and doesn't create performance/security or any other issues. Since you should never maintain generated code by hand, it doesn't matter if it's not up to your usual coding standards. – Hila Oct 04 '10 at 15:32
  • 5
    That's fine for you to disagree. However, if you're going to take the time to create a code generator then why not take the time to make the code generated pretty? Once generated, I don't know who made it, how it was made, nor the intention of it unless it's just as readable/maintainable as all other parts. Sometimes generators are there only to create a starting point rather than the full-fledged finished product. – wheaties Oct 04 '10 at 15:53
  • I think it really depends on the individual case. If you are using code generation to generate tedious and repetitive code, then it should really be "good code". But code generation is usually a bad solution to that problem. On the other hand, if you are generating code to build a hyper-optimized version of something, I wouldn't expect the code to be readable. I'd just include a comment directing the coder to look at the generating code. – Winston Ewert Oct 04 '10 at 19:37
  • 1
    Also, if the generation of the code is part of your build (i.e. it gets re-generated every build) then it doesn't make as much sense to produce "beautiful" code. But if you're going to generate the code once and that's it, then it's a different story. – Dean Harding Oct 04 '10 at 23:15
  • 5
    Hila, you should never maintain generated code by hand, but when the day comes that you need to change that code due to new/changing requirements, you need the code to be clear and comprehensible so you can easily make the necessary changes to the generator, and then re-generate. – Carson63000 Oct 05 '10 at 00:47
  • 6
    The generated code doesn't have to be pretty enough for maintenance, but it needs to be intelligible enough for debugging and for validation. – Huperniketes Oct 15 '10 at 17:33
  • @wheaties thanks! There is really no excuse for messy generated code except of course extreme inexperience, which is also a reason to not automate anything in any way because that would place horrible, horrible code in charge of way more things than it deserves – yeoman Jun 12 '20 at 12:30
6

A code generator is a type of compiler. You don't worry about how pretty the compiler output is, you just work with the source code. Using it and then hand-modifying the output is often harder than just writing it from scratch in a form comprehensible by humans, and means you can't use the code generator again without a lot of work, since you'll have to apply the same changes to the same incomprehensible code accurately.

Therefore, they can be fine if they're part of the build process, and documented as such. The input to the generator is then the source code, and whatever it produces is intermediate results, not to be messed with.

However, if somebody's using one to produce incomprehensible code that's supposed to be used as source, then that person's producing bad code. It doesn't matter if the person is producing bad code mechanically or by hand, it's still bad code, and you still have a quality problem with it.

Therefore, you need to treat this as any other developer cutting corners and writing bad code. I don't know how you handle that at your shop.

David Thornley
  • 20,238
  • 2
  • 55
  • 82
  • Yes, the code generators you and I are writing for our projects is certainly as immaculate and widely tested as clang or javac, so the need to debug the generated code or just have a look inside it is almost fully guaranteed to never arise. – yeoman Jun 12 '20 at 12:34
3

From the comments on other answers it seems like you're asking about team standards rather than code generators themselves.

A code generation tool should be included in the project and should (where appropriate) be part of the build process. An example would be on our team we make use of Subsonic 2.2 which we have generate classes from the database objects on build.

The exe that does this is checked into SVN as part of the project so that a new member of the team could get the new project from svn and immediately build it without having to figure out where all these database classes came from (in this example we don't even include the generated code in svn).

Rob Stevenson-Leggett
  • 383
  • 1
  • 9