Custom File Headers for Generated Files.

Prevention of Editing Generated Code

In every project I've worked on that uses swagger-generated code, somewhere, somebody has wanted to add new fields or methods to a swagger generated file. Instead of modifying the .yaml file, they throw out the code generation, check the generated code into the repository, and begin editing it like ordinary code. Once this process starts, it's very cumbersome to reenable the code generation, so we end up just continuing to modify the once-generated code. The longer a project lasts, the more likely it is that somebody will do this.

This probably happens because some new people have joined the project and don't know how the generator works. Often, their colleagues don't know either.

This could be avoided if every generated file had a file header that said something like this: (For a .java file, in this example)

/*
 * Warning: This is generated code. Do not edit. The source for this generated code is in the file RecipeSpec.yaml. For
 * instructions on how to run the generator, see the README.md file section on code generation.
*/

Unfortunately, I can't add add this to my generated files, because, hey, it's generated code.

Proposed Solution

The code generators should offer an option to specify a customizable file header for each generated file. This should be easy to add. If a generator creates more than one type of file (I don't know if this is the case), it may be desirable to specify a directory where file headers may be found. And each header could be a file named header, with the extension of the file type that it belongs to. Or the option could just specify a path to a header file. The generator would put this header at the top of every generated file, and the developers would be able to customize it.

Alternatives

I always include a section in the README.md file that explains the code generation process. But this isn't enough because people who open a generated file don't see anything that would point them to the README.md file. (It sometimes amazes me that people don't read the README.md file, but this happens.

Start with the generator entry points that assemble generated files and the README.md code-generation instructions; consider how headers could be supplied for the referenced RecipeSpec.yaml input and different output types. Done means a documented, customizable header option is applied to generated files without editing generated output, with coverage for supported file types.