dart3-idioms-and-coding-standards

Start with an enum when the set is closed and every member is payload-free, since enums get compiler exhaustiveness in a switch. Convert to a sealed class with final class variants the moment any member needs a field, rather than adding nullable fields to the enum.

Switch on a sealed type or enum and omit both default: and case _:. A missing branch then reports non_exhaustive_switch_statement from dart analyze and fails dart compile, so adding a variant becomes a compile error at every unhandled site.

Hand-roll trivial immutables of one to three fields with @immutable, a const constructor, and final fields. Use freezed when copyWith, equality, and sealed-union boilerplate dominates; skip equatable since operator == plus Object.hash covers it in about five lines.

late disables null-safety checking and throws LateInitializationError at runtime, while ! throws TypeError when wrong. Model genuinely absent values as nullable T? and handle them with ?., ??, or flow promotion instead.

Methods cap at roughly 30 lines, build() at 80, files at 300, logic nesting at 3, and widget build nesting at 5. These are firm refactor prompts, and a cohesive overrun such as a single state machine can be justified in the PR.

Records suit ephemeral multi-value returns inside a single layer, like an (int row, int col) coordinate, with named fields once they survive a few lines. Never return a record from a repository, store it, or pass it across a widget constructor; use a named class instead.