dart3-idioms-and-coding-standards

Dart 3 idioms and coding standards

Modern Dart 3.x, value-type-first, total functions for domain logic. A language feature earns its place when it converts a runtime silence into a compile error; everything else is decoration. This skill governs how each declaration is typed, named, kept immutable, and kept total — the error-handling architecture that rides on top of these mechanics lives in error-handling-typed-results.

Read the reference for the task at hand:

• references/construct-verdict-table.md — the feature-by-feature verdict table (sealed / enum / record / class modifiers / extension type / codegen packages), with the rationale for each Use / Skip.
• references/immutability-and-equality.md — immutable value types, copyWith, when to hand-write ==/hashCode, and stable-identity vs value-equality.
• references/complexity-and-honesty.md — the length/nesting limits with their evidence, and the late/!/dynamic honesty-dodge bans in full.

Run scripts/check-dart3-idioms.sh before a PR.

Non-negotiable rules

1. A switch on a sealed type or enum carries no default: and no case _:. A wildcard makes the switch compile forever, discarding the one compile-time guarantee the type exists for — adding a variant then falls through silently at runtime. Exhaustiveness is the whole product.
2. Reach for exactly three class modifiers; ignore the rest. sealed class for a closed variant set the compiler must exhaust; final class for every concrete leaf; abstract interface class for a seam a test fake implements. Default concrete types to final. Skip base, extension type, primary constructors, and macros.
3. Model closed sets of individually actionable cases as a sealed hierarchy, payload-free closed sets as an enum. Start with enum; convert to sealed + final class the moment any member needs a field. Never bolt nullable fields onto an enum for data that applies to only some members — that turns every access into a null-check the compiler cannot reason about.
4. Records never cross a layer boundary. A record is a nameless, positional, undocumented shape — fine for an ephemeral multi-value return inside one layer. The moment a shape is returned from a repository, stored, or passed to a widget constructor, it is a named class.
5. Domain values are immutable: final fields, a const constructor where legal, value equality, and copyWith to derive. Mutating a value handed to a widget is a rebuild-and-golden-test killer. Prefer final locals and const constructors everywhere the analyzer allows.
6. Identity is an explicit stable field, never equals-on-all-fields. A value type used in a list or as a map key carries final String id (or a typed id). Deriving identity from all fields collapses two distinct entities that happen to share values (two Items both named "Draft") into one.
7. Make illegal states unrepresentable. Encode a discriminated choice as a sealed variant or an enum-keyed union, not as a bag of nullable fields where only one is ever set. If the type cannot express the bad state, no branch has to guard against it.
8. Domain functions are total — they never throw. Every pure function returns a value for every input; uncertainty is an explicit output (a clamped value, a "no result within N steps" outcome, a low-confidence flag). Programmer invariants use assert (stripped in release), never throw. Recoverable I/O failures return a typed result — see error-handling-typed-results.
9. No honesty dodges: no late to dodge nullability, no ! on a value that matters, no dynamic/Map<String, dynamic> as an ad-hoc model. Each hides a runtime failure the type system would otherwise force you to handle. Use ?./??/promotion for null, and a typed model for structured data.
10. Effective Dart casing, verbatim; constants are lowerCamelCase. UpperCamelCase types/extensions/enums; lowercase_with_underscores files/dirs/import prefixes; lowerCamelCase vars/params/methods/constants (maxItems, never MAX_ITEMS); acronyms over two letters capitalize as a word (JsonMap, HttpClient, not JSONMap). File name = its primary declaration.
11. Respect the complexity limits as firm defaults — this table is the library's single source of truth; other skills cite it, they do not restate numbers: method ≤ ~30 lines, build() ≤ ~80, file ≤ ~300, class public API ≤ ~10 members, positional params ≤ 3, logic nesting ≤ 3. Widget build trees legitimately nest deeper — widget build nesting ≤ 5 is the one explicit exception (referenced by widget-composition). Refactor prompts, not laws — a cohesive overrun (a single state machine scattered across five fragments is worse) is justified in the PR.
12. Prefer immutable value types; hand-roll trivial ones, reach for freezed when the boilerplate dominates. For a trivial immutable (1–3 fields) hand-write @immutable + const ctor + final fields (+ manual == / Object.hash when a map key). For a domain or UI-state value type where copyWith/==/hashCode/sealed-union boilerplate gets tedious, freezed is allowed and is the default — *.freezed.dart is a first-class generated artifact. Skip equatable (five lines of == + Object.hash cover it), fpdart/dartz (an Either erases exhaustiveness), and any --enable-experiment flag (an abandoned repo stops building the day the flag is dropped).