Dart Best Practices

Analogy categoryAnalogies

Writing Idiomatic Dart Code

Google's Effective Dart guide and the package:lints (or package:flutter_lints for Flutter projects) linter rule set define what 'idiomatic' means in practice: use lowerCamelCase for variables, methods, and parameters, UpperCamelCase for classes, mixins, and typedefs, and lowercase_with_underscores for file and package names. Beyond naming, idiomatic Dart favors expression-bodied functions for one-liners, cascades (..) for fluent object configuration, and trailing commas in multi-line argument lists so dart format produces stable, readable diffs.

🏏

Cricket analogy: Following Effective Dart's naming rules is like a franchise enforcing a strict jersey-numbering scheme so every scoreboard and commentary team reads player names the same way, whether it's a Test match or a T20 tie.

Null Safety and Immutability

Prefer final for variables assigned once and const for compile-time constants; both prevent accidental reassignment bugs and, in Flutter, const constructors let the framework skip rebuilding unchanged widget subtrees entirely, a real performance win. Avoid late unless you have a genuinely deferred initialization (like a value set in initState), because a late variable accessed before assignment throws a LateInitializationError at runtime instead of being caught by the analyzer at compile time, defeating much of what sound null safety is meant to prevent.

🏏

Cricket analogy: Using final and const is like locking in your playing XI before the toss so nobody can swap a player mid-innings by mistake, while overusing late is like naming a 12th man 'confirmed starter' and only discovering at the toss he isn't actually available.

Effective Collections and Async Patterns

Use collection-if and collection-for inside list/set/map literals ([if (isAdmin) 'settings', for (final u in users) u.name]) instead of manually building lists with loops and conditionals, and prefer the spread operator (...) to merge collections rather than addAll. For async code, prefer async/await over chaining .then() calls since it reads top-to-bottom and composes better with try/catch; use unawaited() from dart:async when you deliberately want to fire a Future without waiting, so the linter and future readers know it was intentional rather than a missed await.

🏏

Cricket analogy: Collection-if inside a list literal is like a scorer conditionally adding 'DNB' to the batting card only if a player didn't bat, right inline, instead of writing the whole card and editing it afterward.

dart

// Bad: mutable field, no const, .then() chains
class UserCard extends StatelessWidget {
  UserCard({required this.name});
  String name;

  Widget build(BuildContext context) {
    return fetchAvatar(name).then((url) {
      return Image.network(url);
    });
  }
}

// Good: immutable field, const constructor, async/await
class UserCard extends StatelessWidget {
  const UserCard({super.key, required this.name});
  final String name;

  @override
  Widget build(BuildContext context) {
    return FutureBuilder<String>(
      future: fetchAvatar(name),
      builder: (context, snapshot) {
        if (!snapshot.hasData) return const CircularProgressIndicator();
        return Image.network(snapshot.data!);
      },
    );
  }
}

dart fix --apply can automatically add missing const keywords, convert straightforward .then() chains flagged by the linter, and update deprecated API calls — run it after upgrading the Dart SDK to catch breaking changes early.

Overusing late to silence 'must be initialized' errors is one of the most common ways teams accidentally reintroduce null-safety-style crashes: a LateInitializationError still crashes at runtime, it just moves the failure from compile time to whenever that field is first read.

Code Organization and Tooling

Run dart format . before every commit to enforce a single canonical style (consistent line width and bracket placement), and run dart analyze (or rely on your IDE's live analysis) to catch lint violations and type errors before they reach code review; dart fix --apply can auto-apply many suggested fixes, like adding missing const keywords. Keep files focused, one primary public class per file is a reasonable default, and use part/part of sparingly since barrel files (export statements re-exporting a library's public API) are generally preferred for organizing a package's public surface.

🏏

Cricket analogy: Running dart format before every commit is like every team submitting their scorecards in the exact same official format so the league's central database never chokes on a mismatched entry.

Follow Effective Dart naming: lowerCamelCase for variables/methods, UpperCamelCase for classes/mixins, lowercase_with_underscores for files.
Prefer final and const over mutable variables; const constructors let Flutter skip rebuilding unchanged widget subtrees.
Avoid late unless initialization is genuinely deferred — accessing an unset late variable throws LateInitializationError at runtime.
Use collection-if/collection-for and spread operators instead of manual loops when building list/set/map literals.
Prefer async/await over chained .then() calls for readability and better try/catch composition.
Run dart format and dart analyze before every commit; use dart fix --apply to auto-apply many lint fixes.
Keep one primary public class per file and use barrel export files to curate a package's public API.