Structs & Enums Best Practices

Design data types so invariants live in one place and the compiler helps enforce them.

How to Use This List

• Apply when designing new domain types before writing logic.
• Review during PRs that add bool flags or Option soup.
• Pair with Domain Modeling with Types.

A - Struct Design

• Prefer small focused structs over god objects. Split when fields group into distinct lifecycles.
• Make fields private; expose constructors and accessors. Preserve invariants.
• Use newtypes for IDs and units. struct UserId(u64) prevents argument swaps.
• Derive Debug, Clone, Eq when semantics match. Document when not deriving.
• Avoid public Vec fields unless truly unrestricted. Expose iterators or methods.

B - Enum Design

• Replace boolean pairs with enums when states multiply. enum Phase beats is_started + is_done.
• Put data only on variants that need it. Ready vs Running { token }.
• Use #[non_exhaustive] on extensible public enums. Forward-compatible evolution.
• Transition via methods consuming self. Illegal transitions become type or Result errors.
• Box large variant payloads. Keep enum size reasonable.

C - Pattern Matching

• Keep match arms small; extract helpers. Readable transition functions.
• Prefer if let for single-pattern flows. Reduce noise vs one-arm match.
• Use let else for required patterns. Early return on unexpected shape.
• Avoid unwrap on domain enums in library code. Return Result with context.
• Test every variant in critical paths. Variant addition should fail tests until updated.

D - Serialization and APIs

• Separate wire DTOs from domain types when shapes differ. Validate at boundary.
• Use serde attributes on enums for tagged JSON. #[serde(tag = "type")] etc.
• Document variant semantics in rustdoc. Consumers match externally too.
• Version persisted enum discriminants. Migration plan when reordering variants.
• Do not leak internal enums in public API without stability story. Semver implications.

FAQs

Related

• Structs Basics
• Enums for State Machines
• Traits Basics
• Error Handling Best Practices

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.