Generated source is emitted into the hand-edited tree beside its inputs — what does that habit cost a team?
answer
- who actually owns this file?
- the next build writes it again
- keep it out of the hand-edited tree
- a derived marker at the top
- style, coverage and review read that marker
basics
~20 sMixing machine-written files into the hand-edited tree invites edits that a later re-derivation erases, and it feeds emitted code to style checks, coverage numbers and review. Emit into a separate output directory and mark every file derived.
solid answer
~50 sGenerated source is a build artifact that happens to be readable, and filing it beside hand-written code makes every reader and every tool guess who owns it. Someone eventually fixes a defect in the emitted file; it works locally, then a clean build re-derives the file and the fix is gone. Meanwhile style checks flag machine formatting, coverage percentages move because thousands of emitted lines joined the denominator, and a one-line input change shows up as a several-hundred-line diff in review. The hygiene is two-part: emit into a directory that holds nothing a person wrote, and put a `DO NOT EDIT` marker plus a provenance line at the top of each file so the tools configured to read it — style, coverage, review, search — can skip it and a human knows where the real source is.
code
pseudocode · 10 lines// GENERATED FILE - DO NOT EDIT
// generator: view-mapper
// derived from: Order (declaration in the hand-written tree)
// edits here are lost the next time this file is re-derived
function mapOrder(source)
target = new OrderView()
target.id = source.id
target.total = source.total
return targetgo deeper
Remember the one rule that matters: if a file says it was generated, do not edit it. Find the declaration or description it was derived from and change that instead.
Explain the two separate signals — a dedicated output directory and an in-file derived marker — and name the consumers each one informs: the build, style checks, coverage, review and search.
Show the failure you have actually seen: a fix made in emitted source that survived locally and vanished on a clean build, and the guard you added so the next one is caught in the build rather than in production.
Frame it as a standard other teams inherit: where output lives, what marker every generator must emit, whether emitted lines count toward quality metrics, and who is accountable when a defect is found in machine-written code.
Machine-written source is **output**. It is readable, which is exactly why it gets filed as if a person had written it — and from that moment every tool and every reader has to guess who owns it. ## What a mixed tree costs - **Edits evaporate.** Someone fixes a defect directly in the emitted file. It works locally, it may survive several builds while the inputs are unchanged, and then a re-derivation overwrites the file and the fix is gone — usually somewhere nobody is watching. - **Signals are polluted.** Style checks flag machine formatting. Static analysis reports findings nobody will ever act on. Coverage percentages move because thousands of emitted lines landed in the denominator, and the team either chases a number it cannot move or stops trusting the number at all. - **Review drowns.** A one-line change to an input can emit a several-hundred-line diff. A reviewer who cannot tell which half a person wrote reads neither half carefully. - **Deletion gets risky.** When output and input sit together, nobody is sure whether removing a file will be silently undone by the next build or will quietly break it. - **Navigation misleads.** Jump-to-definition lands inside emitted code, and the reader starts studying the artifact instead of its source. ## Location and marker do different jobs Teams often do one and think they have done both. They answer different questions. | Signal | What it says | Who reads it | |---|---|---| | A separate output directory | this whole tree is derived | the build, ignore rules, anyone browsing the repository | | A marker line in each emitted file | this file is derived, do not edit | style checks, coverage, review tooling, the next human | | A provenance comment | which input this file came from | whoever is holding a stack frame at 3am | The directory is the coarse signal and it travels badly: copy one file elsewhere and the signal is gone. The in-file marker travels with the file, which is why the convention exists at all. ## The consumers that have to be told 1. **The build.** It must know the output directory is one it writes to and, on a clean build, one it may delete outright. 2. **Style and static analysis.** Machine formatting is not a defect, and an unused emitted helper is not dead code the team should delete. 3. **Coverage.** Decide deliberately whether emitted lines are in the denominator. Either answer is defensible; an accidental answer is not. 4. **Review tooling.** Collapse or exclude emitted diffs so attention goes to the input change that caused them. 5. **Version-control ignore rules**, if the team chose not to commit the output — a separate decision, but one the directory boundary makes cheap either way. ## Where a change belongs The operating rule is that a defect visible in emitted source is never fixed in emitted source. It is fixed in the **input** — the declaration or description the generator read — or in the **template or generator** that turned the input into text. If neither can express what is needed, the escape hatch is a hand-written extension point: emit a base or a partial piece that hand-written code extends, so the human contribution lives in a file the generator never writes. That is the difference between an extension and an edit, and it is the whole of the discipline. ## What hygiene does not fix A marker is a convention, not an enforcement. Nothing stops someone editing a file that says `DO NOT EDIT`; the marker only makes the mistake visible and makes the loss explicable afterwards. Two cheap guards make it more than a comment: a build step that fails when a file under the output directory has been modified relative to what the generator would emit, and a review rule that treats any hand edit under that directory as a defect regardless of what it does. Both depend on the generator producing the same bytes for the same inputs, which is why output hygiene and reproducible emission are the same piece of engineering rather than two.
- If emitted diffs are excluded from review, what should the reviewer actually read?The input change and the generator or template change that caused the emission, since those are the only files a person wrote. The emitted diff is still useful as evidence — skim it to confirm the change had the effect the author claims, especially when a generator or template was touched, because that one edit fans out across every output file.
- Someone genuinely needs behaviour the generator cannot express. Where does it go?Into a hand-written file that extends or wraps the emitted one, never into the emitted file itself. Generators that expect this emit a piece designed to be extended and keep the extension point stable. If the need recurs, that is a signal to change the input description or the template rather than to keep bolting on wrappers.
- Does a derived marker mean emitted code should be excluded from coverage?Not automatically — it means the question has to be answered on purpose. Emitted code that carries real logic is worth measuring; emitted boilerplate mostly adds a large, unmovable denominator. What matters is that the team chooses, records the choice, and does not let a percentage drift because nobody noticed which lines were machine-written.
It is the difference between a printed report and the spreadsheet behind it. Correcting a number with a pen changes nothing, because the next print run comes from the spreadsheet.
saying these in an interview costs you the question
- Says a quick hand edit to an emitted file is fine
- Assumes a build merges hand edits with newly emitted text
- Chases a coverage number that machine-written lines dominate
- Reads a huge emitted diff instead of the one-line input change
- Thinks tools recognise machine-written files without being told
- Treats the output directory as a place people may also author files