Effective Dart — non-default conventions

Contract

Enforces the arbitrary Effective Dart spellings, keywords, and shapes that a model does NOT produce by default. Apply to every piece of Dart/Flutter code you write or refactor: identifiers, error handling, strings, collections, async signatures, and doc comments.

Rules (the complete spec)

R1 — Acronyms in identifiers are word-cased

Treat an acronym/abbreviation longer than two letters as a single word: only its first letter is capitalized inside UpperCamelCase, and it is all-lowercase inside lowerCamelCase.

• Write JsonParser, UrlBuilder, HtmlSanitizer, CsvExporter, PdfGenerator, XmlValidator,

ApiClient, HttpRequest, RestApiClient. NEVER JSONParser, URLBuilder, HTMLSanitizer, CSVExporter, PDFGenerator, XMLValidator, APIClient, HTTPRequest.

• Inside lowerCamelCase the acronym is lowercase when leading (jsonBody, apiClient,

httpResponse) and word-cased when interior (parseJsonBody, buildUrl, sendHttpRequest).

R2 — Re-raise with rethrow, never throw e;

To propagate the caught exception unchanged, use the bare keyword rethrow. throw e; discards the original stack trace. Logging-then-propagating is } on X catch (e) { log(e); rethrow; }.

R3 — Catch one failure kind with a typed on clause

Handle a specific exception with on FormatException catch (e). Do NOT use a bare catch (e) (it swallows every error type) or .catchError(...) when you only mean to handle one kind.

R4 — Split long strings with adjacent literals, never +

Break a long string literal across lines by placing two or more quoted strings side by side; the compiler concatenates them at no runtime cost. NEVER join the pieces with the + operator.

R5 — Filter a collection by type with whereType<T>()

To keep only the elements of a type, call whereType<T>(). Do NOT write .where((e) => e is T) and do NOT chain .where(...).cast<T>().

R6 — Async members with no result return Future<void>

An async method that produces no value declares return type Future<void>. NEVER bare void, bare Future, or Future<Null>.

R7 — Boolean doc comments begin with "Whether"

A documentation comment on a boolean property/getter starts with the word Whether, e.g. /// Whether the token has expired. NEVER "Returns true if…" or "Checks if…".

R8 — Use /// doc comments and [bracket] references

Document public APIs with /// (never /* */ block comments, never plain //). Refer to parameters, return values, and exception types in prose with square brackets: [a], [id], [ArgumentError]. The first line is a single-sentence summary ending in a period; doc comments go before any metadata annotation (@override).

R9 — Empty constructor bodies end with ;, never {}

A constructor with no body is Logger();, not Logger() {}.

R10 — Property-like reads are getters, not getX() methods

A conceptual property read is a getter: String get fullName => '$first $last';. NEVER expose it as a getFullName() method.

Adjacent surface (apply for completeness)

• Classes/enums/typedefs/extensions → UpperCamelCase; files/dirs → lowercase_with_underscores;

variables/params/functions → lowerCamelCase.

• Annotate return types and parameter types on declarations, and variables without initializers.
• Prefer final over var when a local never changes; const for compile-time constants.
• Curly braces on all flow-control bodies, even one-liners.

Worked examples (BEFORE = base default, AFTER = conforming)

R1 acronym casing

dart
// BEFORE
class JSONParser { Model parseJSON(String body) => ...; }
// AFTER
class JsonParser { Model parseJson(String body) => ...; }

R2 rethrow

dart
// BEFORE
try { read(); } catch (e) { log(e); throw e; }
// AFTER
try { read(); } catch (e) { log(e); rethrow; }

R3 typed on clause

dart
// BEFORE
try { return int.parse(s); } catch (e) { return null; }
// AFTER
try { return int.parse(s); } on FormatException catch (_) { return null; }

R4 adjacent string literals

dart
// BEFORE
const help = 'Usage: tool [options] ' + 'run the pipeline ' + 'and exit.';
// AFTER
const help = 'Usage: tool [options] '
    'run the pipeline '
    'and exit.';

R5 whereType

dart
// BEFORE
final ints = values.where((e) => e is int).cast<int>();
// AFTER
final ints = values.whereType<int>();

R6 Future<void>

dart
// BEFORE
Future saveSettings() async { await disk.write(data); }
// AFTER
Future<void> saveSettings() async { await disk.write(data); }

R7 "Whether" docs

dart
// BEFORE
/// Returns true if the token has expired.
bool get isExpired => DateTime.now().isAfter(expiry);
// AFTER
/// Whether the token has expired.
bool get isExpired => DateTime.now().isAfter(expiry);

R8 /// + bracket refs

dart
// BEFORE
/* Divides a by b. Throws if b is zero. */
int divide(int a, int b) => ...;
// AFTER
/// Returns the quotient of [a] divided by [b].
///
/// Throws [ArgumentError] if [b] is zero.
int divide(int a, int b) => ...;

R9 empty constructor

dart
// BEFORE
class Logger { Logger() {} }
// AFTER
class Logger { Logger(); }

R10 getter not getX()

dart
// BEFORE
String getFullName() => '$firstName $lastName';
// AFTER
String get fullName => '$firstName $lastName';

Edge cases & exceptions

• Two-letter acronyms vs abbreviations. A two-letter acronym like IO stays fully capitalized

(IOSink). A two-letter abbreviation like ID is word-cased (Id, userId, not userID). The "word-case it" rule kicks in strictly for length > 2 (Http, Json).

• rethrow only re-raises the in-flight exception. If you must throw a different error, that is

a genuine throw NewError(...) — R2 forbids throw e; (the same object), not deliberately raising a new one.

• whereType vs cast. Use whereType<T>() to select elements of a type; cast<T>() is for

asserting an already-homogeneous list. Don't reach for cast to do filtering.

• Future<void> vs void. A synchronous callback that returns nothing is void. Only an

async member (or one returning a future) uses Future<void>.

• Bracket refs need an in-scope identifier. [a] works because a is a parameter; don't bracket

arbitrary prose words that aren't real identifiers.

• Block comment for license headers is fine. R8 governs API doc comments; a top-of-file /* */

license banner is not a doc comment and is exempt.

Do / Don't

• DON'T write JSONParser, URLBuilder, APIClient. DO write JsonParser, UrlBuilder, ApiClient.
• DON'T throw e;. DO rethrow;.
• DON'T catch (e) to handle one kind. DO on FormatException catch (e).
• DON'T 'a' + 'b' across lines. DO adjacent literals 'a' 'b'.
• DON'T .where((e) => e is T). DO whereType<T>().
• DON'T return bare void/Future from a no-value async member. DO Future<void>.
• DON'T start a boolean doc with "Returns true if". DO start with "Whether".
• DON'T document with /* */. DO use /// with [bracket] references.
• DON'T write Logger() {}. DO write Logger();.
• DON'T expose getFullName(). DO expose String get fullName.

Common mistakes (the base's wrong defaults)

• Spelling acronyms in all-caps because that is the common English style — Dart overrides it.
• Reaching for throw e; out of habit from other languages, losing the stack trace.
• Catching broadly with catch (e) "to be safe," which hides unrelated bugs.
• Concatenating long strings with + as in Java/JS.
• Writing predicate-based .where(...is T) instead of the built-in whereType.
• Declaring void/Future on an async no-value method.
• Opening boolean docs with "Returns true if…" instead of "Whether…".
• Emitting getX() accessor methods instead of Dart getters.

Quick checklist

• ] Acronyms word-cased (Json, Url, Api, Http, Html, Csv, Pdf, Xml).
• ] rethrow (not throw e;); typed on X catch (not bare catch).
• ] Long strings = adjacent literals (no +).
• ] whereType<T>() for type filtering.
• ] No-value async returns Future<void>.
• ] Boolean docs start "Whether"; /// + [bracket] refs.
• ] Empty constructor Name();; property reads are getters.