Skip to content

[B] Principles for Code Generation

Jump to bottom
Roberto Artigas edited this page Jan 26, 2026 · 1 revision

These should be Non-Negotiable Principles for Code Generation

Principles, Rationale, and Anti-Patterns

This document combines the core principles of responsible code generation with the anti-patterns that violate them.

It defines the minimum standard for using code generation safely in long-lived, professional software systems.

If a code-generation approach violates any of these principles, it should be considered architecturally unsafe.

Principle 1: Full Ownership and Control of Templates

Principle

You must own, understand, and control the templates that generate your code.

What This Means

  • Templates are versioned with source control.
  • Templates can be modified, replaced, or removed without vendor lock-in.
  • Generated output is explainable by inspecting templates.
  • No black-box generation in production systems.

Anti-Patterns

  • Black-box or proprietary generators
  • Vendor-locked template formats
  • Silent template changes without versioning
  • Debugging generated output instead of fixing templates

Failure Modes

  • Inability to upgrade or migrate
  • Regeneration fear
  • Undocumented system behavior

Principle 2: Metadata Is a First-Class, Independent Artifact

Principle

Metadata must be collected separately and evolve independently of code generation.

What This Means

  • Metadata is explicit, durable, and human-readable.
  • Metadata has its own schema, versioning, and validation.
  • Code generation consumes metadata but does not own it.

Anti-Patterns

  • Metadata embedded in generated code
  • Implicit metadata inferred from conventions
  • Generator-owned metadata formats
  • Undocumented metadata schemas

Failure Modes

  • Fragile regeneration
  • Silent data corruption
  • High onboarding cost

Principle 3: Deterministic, One-Click Regeneration

Principle

Generated code must be reproducible exactly, at any time.

What This Means

  • A single documented command regenerates all generated code.
  • Output is deterministic for the same inputs.
  • Regeneration works years later, not just today.

Anti-Patterns

  • Multi-step manual regeneration
  • Environment-dependent generation
  • Non-deterministic output (timestamps, random ordering)
  • Partial regeneration dependencies

Failure Modes

  • Non-reproducible builds
  • “Works on my machine” generation
  • Impossible disaster recovery

Principle 4: Handcrafted Code Is Protected and Respected

Principle

Human-written code must be isolated and never overwritten.

What This Means

  • Clear separation between generated and handwritten code.
  • Generated files are disposable and marked as such.
  • Extension points are intentional and documented.

Anti-Patterns

  • Generator overwrites edited files
  • Mixed generated and handwritten code
  • Hidden or undocumented extension points
  • Teams afraid to regenerate

Failure Modes

  • Loss of trust in tooling
  • Forked or abandoned generators
  • Manual patches that rot

Principle 5: Generated Code Must Meet or Exceed Handwritten Quality

Principle

Generated code must be clean, testable, performant, and maintainable.

What This Means

  • Generated code follows the same standards as handwritten code.
  • No unnecessary abstraction or bloat.
  • Code is debuggable and testable.

Anti-Patterns

  • Code bloat generators
  • Excessive abstraction “to be generic”
  • Untestable generated code
  • Performance-ignorant generation

Failure Modes

  • Debugging paralysis
  • Performance regressions
  • Long-term maintenance collapse

Cross-Cutting Anti-Patterns

Generation as Magic

  • Developers don’t understand the generator.
  • Output is blindly trusted.
  • Root cause analysis is impossible.

Never Regenerate Again

  • Generated code is treated as frozen.
  • Templates rot while code diverges.
  • Generator becomes irrelevant.

Generator as Architecture

  • Architectural decisions hidden in templates.
  • Generator changes are riskier than refactors.

Red Flags Checklist

Investigate immediately if you hear:

  • “Don’t touch the generator.”
  • “We regenerated once, years ago.”
  • “Nobody knows how this file was created.”
  • “It’s faster to edit the generated code directly.”
  • “We’re afraid to upgrade the generator.”

Summary: The Responsibility Contract

Code generation is leverage.

Used correctly, it:

  • reduces repetition,
  • improves consistency,
  • and amplifies human intent.

Used poorly, it:

  • automates mistakes,
  • hides complexity,
  • and compounds technical debt.

Closing Insight

Code generation does not remove responsibility, it concentrates it.

These principles exist to ensure that concentration works in your favor.

Code Wiki Main Repositories

"We stand for a living wage. Wages are subnormal if they fail to provide a living for those who devote their time and energy to industrial occupations. The monetary equivalent of a living wage varies according to local conditions, but most include enough to secure the elements of a normal standard of living -- a standard high enough to make morality possible, to provide for education and recreation, to care for immature members of the family, to maintain the family during periods of sickness, and to permit of reasonable saving for old age."
-Franklin D. Roosevelt

Clone this wiki locally