A team generates Java classes from a domain model, but developers need to hand-write business logic inside those same generated files. If the model changes and the generator runs again, how do you avoid destroying the hand-written code, and what does this problem reveal about round-trip engineering?

## The problem the term names **Round-trip engineering** names the general problem of keeping two representations, a model and its generated code, consistent as both change over time, ideally in both directions: model changes should regenerate code, and in some visions, code changes should be reflected back into the model. In practice, most tooling only solves half of that problem well: preserving hand-written additions when the model-driven side regenerates. That narrower problem is what shows up constantly in real projects, and it has two dominant solutions, each with a different mechanism and a different failure profile: - **protected regions** - the **generation-gap pattern** ## Protected regions Protected regions work by convention inside a single generated file. The generator emits a file as usual, but wraps designated insertion points with recognizable markers, for example `// BEGIN USER CODE` and `// END USER CODE`, often keyed by a stable identifier tied to the model element that produced that region. On the next generation run, before writing the new file, the generator (or a merge step): 1. first reads the existing file on disk, 2. extracts whatever text currently sits between each pair of markers, 3. and splices that text back into the newly generated content at the matching markers, overwriting everything else. This requires the generator to essentially parse its own previous output, at least well enough to find marker pairs reliably, which is why marker syntax has to be something the generator can locate unambiguously (a comment format the target language will never itself produce incidentally). Tools like the old Eclipse EMF generator's `@generated NOT` javadoc tag work on a related principle: a method tagged `@generated` is safe to overwrite, but if a developer edits the method body and the tool detects the tag was manually changed to `@generated NOT`, it treats the whole method as hand-owned and skips regenerating it. ## The generation-gap pattern The generation-gap pattern takes a structurally different approach: instead of merging text inside one file, it splits ownership across two files so there is nothing to merge. The generator fully owns one artifact, commonly an abstract base class or one half of a partial class (in languages that support partial classes, like C#), regenerating it wholesale every time with no preserved content. Hand-written logic lives in a second file that the generator never touches, which extends, implements, or is the other half of the generated artifact. Because the two files have disjoint, non-overlapping ownership, regeneration is trivially safe: delete and rewrite the generated file completely, and the hand-written file is simply never opened by the generator. This is generally considered more robust than protected regions because it does not depend on marker-parsing correctness, but it does require the target language and the project's structure to support the split (partial classes, or a base-class-plus-subclass convention that the team consistently follows). ## The trade-off: fragility versus flexibility The trade-off between the two is fragility versus flexibility. - **Protected regions** let hand-written code live physically close to, or interleaved with, generated code, which some teams find more convenient to navigate, but the mechanism is fragile: a marker accidentally deleted, renamed, or duplicated during a manual edit silently breaks the merge, and the next regeneration either destroys the hand-written code (if the marker is gone) or leaves stale duplicate content (if the merge misfires). - **File splitting** is more robust and less error-prone, but it forces a specific file/class layout on the codebase and, in languages without partial classes, means every generated method a developer wants to override must have been designed as an overridable extension point ahead of time, which the generator's author has to anticipate. ## Where it shows up The production failure that both mechanisms exist to prevent, and that still happens when a team skips them entirely, is straightforward and painful: a developer opens a generated file, adds real business logic directly into a generated method because there is no marker or split file offering a safe place to do it, the model changes for an unrelated reason weeks later, someone reruns the generator, and the hand-written logic is silently gone, discovered only when tests fail or, worse, in production. A concrete, widely known real-world instance of these mechanisms is JPA/Hibernate entity generation from a database schema or UML model: generators commonly emit an abstract `BaseCustomer` class regenerated on every schema change, plus a `Customer extends BaseCustomer` file created once and never regenerated, letting developers freely add business methods to `Customer` with zero risk from future regenerations, this is the generation-gap pattern in its most common industrial form.