design-pattern-builder

Skill: Builder

Intent

Separate complex object assembly from final representation so construction can proceed in controlled steps, with reusable assembly flows and optional variation in produced forms.

Applicability Signals

• Signal 1: Constructors have long parameter lists with optional/conditional fields.
• Signal 2: The same conceptual object is assembled through recurring multi-step logic.
• Signal 3: Different output forms share assembly stages but differ in representation.

Contraindications

• Case 1: Object creation is simple and stable; direct construction is clearer.
• Case 2: There are few optional parameters and no meaningful assembly workflow.
• Case 3: Builder state lifecycle risks misuse in concurrent/shared contexts.

Decision Heuristics

• If construction requires explicit sequencing, validation gates, or reusable recipes, prefer Builder.
• If variation is only in subtype choice (not assembly process), Factory Method or Abstract Factory may fit better.
• Decision anti-bias note: avoid builders that just mirror constructor arguments one-to-one with no added control.

Implementation Checklist

• Define builder interface with explicit build-step methods.
• Define product type(s) and required invariants.
• Implement concrete builder storing assembly state safely.
• Optional: define director/recipe for reusable build sequences.
• Add tests for required-step enforcement, optional-step behavior, and invalid build prevention.

Misuse Checks

• Misuse 1: Builder allows build() before required fields are set → Remediation: enforce step validation or staged builder types.
• Misuse 2: Builder instance is reused unintentionally between builds → Remediation: reset state or require one-shot builder instances.
• Misuse 3: Director hardcodes too many scenario-specific branches → Remediation: split recipe definitions by context.

Verification Rubric

• Correctness:
  • Valid sequence produces correct product with required invariants.
  • Optional sequence variants produce expected outputs without side effects.
• Design quality:
  • Construction logic is isolated from product usage logic.
  • Step semantics are explicit and discoverable.
• Regression safety:
  • Tests cover happy path, missing-required-step, and reused-builder scenarios.

Language-Specific Adaptations (Optional)

• TypeScript: staged/fluent builders can use generic state markers to enforce order at compile time.
• Python: prefer explicit validation in build() and immutable produced objects where practical.
• Go: use explicit setter methods plus Build() (T, error) to enforce runtime validation.

Related Patterns (Optional)

• Prototype: use when cloning baseline instances is cheaper than reconstructing via steps.
• Abstract Factory: use when selecting compatible product families, not stepwise assembly.

Attribution & Sources

• Source Site: Refactoring.Guru
• Source URLs:
  • https://refactoring.guru/design-patterns/builder
  • https://refactoring.guru/design-patterns
• Derivation Note: Concepts derived from referenced sources; explanatory wording rewritten for this repository.
• Policy Note: This artifact intentionally includes no direct quotes and no Refactoring.Guru images.