languages/dart.md
language: dart extensions: [".dart"]
Dart / Flutter — Language-Specific Review Notes
Load this file alongside rules/universal.md. Universal rules are not repeated here — only Dart and Flutter-specific rules and idioms.
PR Analyzer — Dart / Flutter Risk Signals
print()statements left in production code — use a logging package// ignore:lint suppression comments — verify they are justified!null assertion operator used broadly without justification- Hardcoded API keys, tokens, or URLs in Dart source — use environment variables or a secrets package
TODO/FIXMEnear widget lifecycle or state management code
Code Quality — Dart Checks
dynamicused where a concrete type is known — defeats static analysis!(null assertion) used broadly — prefer null-safe patternsStatefulWidgetused whereStatelessWidgetsuffices — prefer statelesssetStatecalled with heavy computation inside — offload before callingBuildContextused across async gaps without checkingmounted- Missing
constconstructor on widgets that could be constant
Security
- Flag API keys or secrets hardcoded in Dart source or
pubspec.yaml— use--dart-defineor a secrets manager - Flag
httppackage used without certificate validation disabled intentionally - Flag
SharedPreferencesused to store sensitive data — useflutter_secure_storage - Flag user-controlled input used in
dart:iofile path operations without sanitization - Flag
WebViewloading arbitrary user-supplied URLs without validation - Flag deep link / URL scheme handlers that don't validate the incoming URL before acting on it
Async / Concurrency
- Flag
BuildContextused after anawaitwithout checkingif (!mounted) return— context may be invalid - Flag
Futurereturned but notawait-ed and without.catchError()orunawaited()— floating future - Flag
Isolate.spawnwithout a clear message-passing protocol - Flag heavy computation on the main isolate — offload with
compute()orIsolate.run() - Flag
StreamControllernot closed when the owning widget is disposed — memory leak - Flag
async*/yield*generators with no error handling on the stream consumer side
Resource Management
- Flag
StreamControllernot closed indispose() - Flag
AnimationControllernot disposed indispose() - Flag
TextEditingController/FocusNode/ScrollControllernot disposed indispose() - Flag
Timernot cancelled indispose() - Flag listeners added to
ChangeNotifier/ValueNotifierwithout a correspondingremoveListener
Exception Handling
- Flag empty
catchblocks — swallowed errors - Flag
catchErrorwith no handler body — silent failure - Flag
Future.errornot surfaced to the UI — show an error state - Flag
FlutterError.onErroroverridden without calling the original handler - Prefer typed
on ExceptionType catch (e)over genericcatch (e)where the exception type is known
Performance
- Flag
setStatecalled for changes that only affect a small subtree — useValueNotifier/provider/Riverpodto scope rebuilds - Flag expensive computation inside
build()— move toinitState, a controller, or aFutureBuilder - Flag
ListViewwithoutListView.builderfor long or infinite lists — builds all children at once - Flag missing
conston widgets that never change — prevents unnecessary rebuilds - Flag
Image.networkwithout a caching package in a list — re-downloads on every scroll - Flag
RepaintBoundarymissing around frequently-repainted widgets (animations, counters)
Idioms and Best Practices
Null Safety
- Prefer
?.safe navigation and??null coalescing over!assertions - Use
lateonly when initialization is guaranteed before first access — document why - Prefer early returns over deeply nested null checks
Flutter Widget Patterns
- Prefer
StatelessWidget+ external state management overStatefulWidgetfor business logic - Keep
build()methods pure — no side effects, no heavy computation - Extract repeated widget subtrees into named widget classes, not just methods, for better rebuild granularity
- Use
constconstructors wherever possible — compile-time constant widgets skip rebuilds entirely
State Management
- Do not mix multiple state management approaches in the same feature
- Flag business logic inside
build()— it belongs in a ViewModel, Notifier, or BLoC - Prefer
Riverpod/provider/BLoCover rawsetStatefor anything beyond local UI state
Modern Dart (3.x)
- Prefer
sealedclasses for exhaustive pattern matching on domain types - Use records (
(int, String)) for lightweight multi-value returns instead of ad hoc classes - Use
switchexpressions with pattern matching instead of longif/elsechains - Prefer
finalfor local variables — immutability by default