Use Builders For Optional Or Validated Fields

RUST-USE-BUILDERS-FOR-OPTIONAL-OR-VALIDATED-FIELDS

Summary

Use builders when construction has many optional inputs or cross-field validation that would make constructors hard to read. Avoid builder APIs for simple values where direct construction communicates the contract better.

Rule

Use builders for many optional fields or cross-field validation.

Why

Constructors with many optional arguments or cross-field validation become hard to call correctly and hard to extend compatibly. Builders let callers name choices, preserve defaults, and delay validation until the full configuration is known.

Helps

Helps APIs avoid long argument lists while giving validation and cross-field defaults a named home.

Limits

Do not add builders for simple structs or functions with a few obvious required parameters. Builders pay off when optional fields, defaults, or validation would otherwise obscure construction.

Agent Instruction

Use builders for many optional fields or cross-field validation because constructors with many optional
arguments or cross-field validation become hard to call correctly and hard to extend compatibly.

Mechanisms

Use a builder type for many optional fields, cross-field validation, staged construction, or fallible finalization. Keep required fields and defaults explicit.