CINXE.COM

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="x-ua-compatible" content="ie=edge"><meta name="viewport" content="width=device-width,initial-scale=1"><script>!function(e,t,a,n){e[n]=e[n]||[],e[n].push({"gtm.start":(new Date).getTime(),event:"gtm.js"});var g=t.getElementsByTagName(a)[0],m=t.createElement(a);m.async=!0,m.src="https://www.googletagmanager.com/gtm.js?id=GTM-5VSZM5J",g.parentNode.insertBefore(m,g)}(window,document,"script","dataLayer")</script><meta name="description" content="Guidelines for using language features to write maintainable code."><title>Effective Dart: Usage | Dart</title><link rel="icon" sizes="64x64" href="/assets/img/logo/dart-64.png" eleventy:ignore><link href="/assets/img/touch-icon-iphone.png" rel="apple-touch-icon" eleventy:ignore><link href="/assets/img/touch-icon-ipad.png" rel="apple-touch-icon" sizes="152x152" eleventy:ignore><link href="/assets/img/touch-icon-iphone-retina.png" rel="apple-touch-icon" sizes="180x180" eleventy:ignore><link href="/assets/img/touch-icon-ipad-retina.png" rel="apple-touch-icon" sizes="167x167" eleventy:ignore><meta name="twitter:card" content="summary"><meta name="twitter:site" content="@dart_lang"><meta name="twitter:title" content="Effective Dart: Usage"><meta name="twitter:description" content="Guidelines for using language features to write maintainable code."><meta property="og:title" content="Effective Dart: Usage"><meta property="og:description" content="Guidelines for using language features to write maintainable code."><meta property="og:url" content="/effective-dart/usage/"><meta property="og:image" content="/assets/img/logo/dart-logo-for-shares.png?2" eleventy:ignore><link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=Google+Sans:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Display:wght@400&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Mono:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Google+Sans+Text:wght@400;500;700&display=swap" rel="stylesheet"><link href="https://fonts.googleapis.com/css2?family=Material+Symbols+Outlined:opsz,wght,FILL,GRAD@24,400,0..1,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css?v=3"><script src="/assets/js/os-tabs.js?v=3"></script><script src="/assets/js/main.js?v=3"></script><script>!function(e,a,t,n,c,o,s){e.GoogleAnalyticsObject=c,e[c]=e[c]||function(){(e[c].q=e[c].q||[]).push(arguments)},e[c].l=1*new Date,o=a.createElement(t),s=a.getElementsByTagName(t)[0],o.async=1,o.src="//www.google-analytics.com/analytics.js",s.parentNode.insertBefore(o,s)}(window,document,"script",0,"ga"),ga("create","UA-26406144-4","auto"),ga("send","pageview")</script></head><body class="default.html"><a id="skip-to-main" class="filled-button" href="#site-content-title" tabindex="1">Skip to main content</a><section id="cookie-notice"><div class="container">dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic.<div class="button-group"><a class="text-button" href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a> <button id="cookie-consent" class="filled-button">OK, got it</button></div></div></section><noscript><iframe src="https://www.googletagmanager.com/ns.html?id=GTM-5VSZM5J" height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript><div id="site-banner" role="alert">Announcing Dart 3.7! Find out about updates to the language, analyzer, pub.dev, and more, in the <a href="https://medium.com/dartlang/announcing-dart-3-7-bf864a1b195c" target="_blank">blog post</a>.</div><header id="site-header"><nav id="mainnav"><div id="menu-toggle">menu</div><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart"></a><ul class="navbar"><li><a href="/overview" class="nav-link">Overview</a></li><li class="mainnav__get-started"><a href="/docs" class="nav-link active">Docs</a></li><li><a href="/community" class="nav-link">Community</a></li><li><a href="/#try-dart" class="nav-link">Try Dart</a></li><li><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="searchfield"><form action="/search" class="site-header-search form-inline" id="cse-search-box"><input type="hidden" name="cx" value="011220921317074318178:_yy-tmb5t_i"> <input type="hidden" name="ie" value="UTF-8"> <input type="hidden" name="hl" value="en"> <input class="site-header-searchfield form-control search-field" type="search" name="q" id="search-main" autocomplete="off" placeholder="Search" aria-label="Search"></form></li></ul></nav></header><div id="site-below-header"><div id="site-main-row"><div id="sidenav"><form action="/search/" class="site-header-search form-inline"><input class="site-header-searchfield form-control search-field" type="search" name="q" id="search-side" autocomplete="off" placeholder="Search" aria-label="Search"></form><ul class="navbar-nav"><li aria-hidden="true"><div class="sidenav-divider"></div></li><li class="nav-item"><a href="/overview" class="nav-link">Overview</a></li><li class="nav-item"><a href="/community" class="nav-link">Community</a></li><li class="nav-item"><a href="https://dartpad.dev" class="nav-link">Try Dart</a></li><li class="nav-item"><a href="/get-dart" class="nav-link">Get Dart</a></li><li class="nav-item"><a href="/docs" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidenav-divider"></div></li></ul><ul class="nav"><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-1" role="button" aria-expanded="false" aria-controls="-sidenav-1">Language expand_more</button><ul class="nav collapse" id="-sidenav-1"><li class="nav-item"><a class="nav-link" href="/language"><div>Introduction</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-2" role="button" aria-expanded="false" aria-controls="-sidenav-1-2">Syntax basics expand_more</button><ul class="nav collapse" id="-sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables"><div>Variables</div></a></li><li class="nav-item"><a class="nav-link" href="/language/operators"><div>Operators</div></a></li><li class="nav-item"><a class="nav-link" href="/language/comments"><div>Comments</div></a></li><li class="nav-item"><a class="nav-link" href="/language/metadata"><div>Metadata</div></a></li><li class="nav-item"><a class="nav-link" href="/language/libraries"><div>Libraries & imports</div></a></li><li class="nav-item"><a class="nav-link" href="/language/keywords"><div>Keywords</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-3" role="button" aria-expanded="false" aria-controls="-sidenav-1-3">Types expand_more</button><ul class="nav collapse" id="-sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types"><div>Built-in types</div></a></li><li class="nav-item"><a class="nav-link" href="/language/records"><div>Records</div></a></li><li class="nav-item"><a class="nav-link" href="/language/collections"><div>Collections</div></a></li><li class="nav-item"><a class="nav-link" href="/language/generics"><div>Generics</div></a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs"><div>Typedefs</div></a></li><li class="nav-item"><a class="nav-link" href="/language/type-system"><div>Type system</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-4" role="button" aria-expanded="false" aria-controls="-sidenav-1-4">Patterns expand_more</button><ul class="nav collapse" id="-sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns"><div>Overview & usage</div></a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types"><div>Pattern types</div></a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener"><div>Applied tutorialopen_in_new</div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions"><div>Functions</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-6" role="button" aria-expanded="false" aria-controls="-sidenav-1-6">Control flow expand_more</button><ul class="nav collapse" id="-sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops"><div>Loops</div></a></li><li class="nav-item"><a class="nav-link" href="/language/branches"><div>Branches</div></a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling"><div>Error handling</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-7" role="button" aria-expanded="false" aria-controls="-sidenav-1-7">Classes & objects expand_more</button><ul class="nav collapse" id="-sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes"><div>Classes</div></a></li><li class="nav-item"><a class="nav-link" href="/language/constructors"><div>Constructors</div></a></li><li class="nav-item"><a class="nav-link" href="/language/methods"><div>Methods</div></a></li><li class="nav-item"><a class="nav-link" href="/language/extend"><div>Extend a class</div></a></li><li class="nav-item"><a class="nav-link" href="/language/mixins"><div>Mixins</div></a></li><li class="nav-item"><a class="nav-link" href="/language/enums"><div>Enums</div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods"><div>Extension methods</div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types"><div>Extension types</div></a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects"><div>Callable objects</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-8" role="button" aria-expanded="false" aria-controls="-sidenav-1-8">Class modifiers expand_more</button><ul class="nav collapse" id="-sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers"><div>Overview & usage</div></a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis"><div>Class modifiers for API maintainers</div></a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference"><div>Reference</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-9" role="button" aria-expanded="false" aria-controls="-sidenav-1-9">Concurrency expand_more</button><ul class="nav collapse" id="-sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/language/async"><div>Asynchronous support</div></a></li><li class="nav-item"><a class="nav-link" href="/language/isolates"><div>Isolates</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-1-10" role="button" aria-expanded="false" aria-controls="-sidenav-1-10">Null safety expand_more</button><ul class="nav collapse" id="-sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety"><div>Sound null safety</div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide"><div>Migrating to null safety</div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety"><div>Understanding null safety</div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety"><div>Unsound null safety</div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq"><div>FAQ</div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-2" role="button" aria-expanded="false" aria-controls="-sidenav-2">Core libraries expand_more</button><ul class="nav collapse" id="-sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core"><div>dart:core</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async"><div>dart:async</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math"><div>dart:math</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert"><div>dart:convert</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io"><div>dart:io</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div>dart:js_interop</div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables"><div>Iterable collections</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-2-10" role="button" aria-expanded="false" aria-controls="-sidenav-2-10">Asynchronous programming expand_more</button><ul class="nav collapse" id="-sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await"><div>Tutorial</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling"><div>Futures and error handling</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams"><div>Using streams</div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams"><div>Creating streams</div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link active collapsible" data-toggle="collapse" data-target="#-sidenav-3" role="button" aria-expanded="true" aria-controls="-sidenav-3">Effective Dart expand_more</button><ul class="nav collapse show" id="-sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style"><div>Style</div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation"><div>Documentation</div></a></li><li class="nav-item"><a class="nav-link active" href="/effective-dart/usage"><div>Usage</div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design"><div>Design</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-4" role="button" aria-expanded="false" aria-controls="-sidenav-4">Packages expand_more</button><ul class="nav collapse" id="-sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages"><div>How to use packages</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages"><div>Commonly used packages</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/create-packages"><div>Creating packages</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing"><div>Publishing packages</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages"><div>Writing package pages</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/workspaces"><div>Workspaces (monorepo support)</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-4-7" role="button" aria-expanded="false" aria-controls="-sidenav-4-7">Package reference expand_more</button><ul class="nav collapse" id="-sidenav-4-7"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies"><div>Dependencies</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary"><div>Glossary</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout"><div>Package layout conventions</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables"><div>Pub environment variables</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec"><div>Pubspec file</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot"><div>Troubleshooting pub</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers"><div>Verified publishers</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories"><div>Security advisories</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning"><div>Versioning</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories"><div>Custom package repositories</div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/tools/pub/private-files"><div>What not to commit</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-5" role="button" aria-expanded="false" aria-controls="-sidenav-5">Development expand_more</button><ul class="nav collapse" id="-sidenav-5"><li class="nav-item"><a class="nav-link" href="/libraries/serialization/json"><div>JSON serialization</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/number-representation"><div>Number representation</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis"><div>Google APIs</div></a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps"><div>Multi-platform apps</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-5-5" role="button" aria-expanded="false" aria-controls="-sidenav-5-5">Command-line & server apps expand_more</button><ul class="nav collapse" id="-sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started"><div>Get started</div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline"><div>Write command-line apps</div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data"><div>Fetch data from the internet</div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver"><div>Write HTTP servers</div></a></li><li class="nav-item"><a class="nav-link" href="/server/libraries"><div>Libraries & packages</div></a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud"><div>Google Cloud</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-5-6" role="button" aria-expanded="false" aria-controls="-sidenav-5-6">Web apps expand_more</button><ul class="nav collapse" id="-sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/web/get-started"><div>Get started</div></a></li><li class="nav-item"><a class="nav-link" href="/web/deployment"><div>Deployment</div></a></li><li class="nav-item"><a class="nav-link" href="/web/libraries"><div>Libraries & packages</div></a></li><li class="nav-item"><a class="nav-link" href="/web/wasm"><div>Wasm compilation</div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/libraries/core/environment-declarations"><div>Environment declarations</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-6" role="button" aria-expanded="false" aria-controls="-sidenav-6">Interoperability expand_more</button><ul class="nav collapse" id="-sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop"><div>C interop</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop"><div>Objective-C & Swift interop</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop"><div>Java & Kotlin interop</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-6-4" role="button" aria-expanded="false" aria-controls="-sidenav-6-4">JavaScript interop expand_more</button><ul class="nav collapse" id="-sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage"><div>Usage</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types"><div>JS types</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials"><div>Tutorials</div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop"><div>Past JS interop</div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web"><div>Web interop</div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-7" role="button" aria-expanded="false" aria-controls="-sidenav-7">Tools & techniques expand_more</button><ul class="nav collapse" id="-sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools"><div>Overview</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-2" role="button" aria-expanded="false" aria-controls="-sidenav-7-2">Editors & debuggers expand_more</button><ul class="nav collapse" id="-sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin"><div>IntelliJ & Android Studio</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code"><div>VS Code</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools"><div>Dart DevTools</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="-sidenav-7-2-4">DartPad expand_more</button><ul class="nav collapse" id="-sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot"><div>Troubleshooting DartPad</div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-3" role="button" aria-expanded="false" aria-controls="-sidenav-7-3">Command-line tools expand_more</button><ul class="nav collapse" id="-sidenav-7-3"><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="-sidenav-7-3-1">Dart SDK expand_more</button><ul class="nav collapse show" id="-sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk"><div>Overview</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool"><div>dart</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze"><div>dart analyze</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile"><div>dart compile</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create"><div>dart create</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc"><div>dart doc</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix"><div>dart fix</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format"><div>dart format</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info"><div>dart info</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd"><div>dart pub</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run"><div>dart run</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test"><div>dart test</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime"><div>dartaotruntime</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags"><div>Experiment flags</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="-sidenav-7-3-2">Other command-line tools expand_more</button><ul class="nav collapse show" id="-sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner"><div>build_runner</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev"><div>webdev</div></a></li></ul></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-4" role="button" aria-expanded="false" aria-controls="-sidenav-7-4">Static analysis expand_more</button><ul class="nav collapse" id="-sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis"><div>Customizing static analysis</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons"><div>Fixing type promotion failures</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules"><div>Linter rules</div></a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages"><div>Diagnostic messages</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-7-5" role="button" aria-expanded="false" aria-controls="-sidenav-7-5">Testing & optimization expand_more</button><ul class="nav collapse" id="-sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/tools/testing"><div>Testing</div></a></li><li class="nav-item"><a class="nav-link" href="/web/debugging"><div>Debugging web apps</div></a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidenav-divider"></div></li><li class="nav-item"><button class="nav-link collapsed collapsible" data-toggle="collapse" data-target="#-sidenav-9" role="button" aria-expanded="false" aria-controls="-sidenav-9">Resources expand_more</button><ul class="nav collapse" id="-sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet"><div>Language cheatsheet</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes"><div>Breaking changes</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/evolution"><div>Language evolution</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/spec"><div>Language specification</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration"><div>Dart 3 migration guide</div></a></li><li class="nav-item"><button class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#-sidenav-9-6" role="button" aria-expanded="false" aria-controls="-sidenav-9-6">Coming from ... expand_more</button><ul class="nav collapse" id="-sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart"><div>JavaScript to Dart</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart"><div>Swift to Dart</div></a></li></ul></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq"><div>FAQ</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary"><div>Glossary</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/books"><div>Books</div></a></li><li class="nav-item"><a class="nav-link" href="/resources/videos"><div>Videos</div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials"><div>Tutorials</div></a></li></ul></li><li class="nav-item"><button class="nav-link collapsible" data-toggle="collapse" data-target="#-sidenav-10" role="button" aria-expanded="true" aria-controls="-sidenav-10">Related sites expand_more</button><ul class="nav collapse show" id="-sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener"><div>API referenceopen_in_new</div></a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener"><div>Blogopen_in_new</div></a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener"><div>DartPad (online editor)open_in_new</div></a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener"><div>Flutteropen_in_new</div></a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener"><div>Package siteopen_in_new</div></a></li></ul></li></ul></div><main id="page-content"><div id="site-toc--side" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry nav-item"><a class="nav-link" href="#libraries">Libraries</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-strings-in-part-of-directives">DO use strings in part of directives</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-import-libraries-that-are-inside-the-src-directory-of-another-package">DON'T import libraries that are inside the src directory of another package</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-allow-an-import-path-to-reach-into-or-out-of-lib">DON'T allow an import path to reach into or out of lib</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-relative-import-paths">PREFER relative import paths</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#null">Null</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#dont-explicitly-initialize-variables-to-null">DON'T explicitly initialize variables to null</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-an-explicit-default-value-of-null">DON'T use an explicit default value of null</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-true-or-false-in-equality-operations">DON'T use true or false in equality operations</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-late-variables-if-you-need-to-check-whether-they-are-initialized">AVOID late variables if you need to check whether they are initialized</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-type-promotion-or-null-check-patterns-for-using-nullable-types">CONSIDER type promotion or null-check patterns for using nullable types</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#strings">Strings</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-adjacent-strings-to-concatenate-string-literals">DO use adjacent strings to concatenate string literals</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-using-interpolation-to-compose-strings-and-values">PREFER using interpolation to compose strings and values</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-curly-braces-in-interpolation-when-not-needed">AVOID using curly braces in interpolation when not needed</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#collections">Collections</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-collection-literals-when-possible">DO use collection literals when possible</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-length-to-see-if-a-collection-is-empty">DON'T use .length to see if a collection is empty</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-iterable-foreach-with-a-function-literal">AVOID using Iterable.forEach() with a function literal</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-list-from-unless-you-intend-to-change-the-type-of-the-result">DON'T use List.from() unless you intend to change the type of the result</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-wheretype-to-filter-a-collection-by-type">DO use whereType() to filter a collection by type</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-cast-when-a-nearby-operation-will-do">DON'T use cast() when a nearby operation will do</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-cast">AVOID using cast()</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#functions">Functions</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-a-function-declaration-to-bind-a-function-to-a-name">DO use a function declaration to bind a function to a name</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-create-a-lambda-when-a-tear-off-will-do">DON'T create a lambda when a tear-off will do</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#variables">Variables</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-follow-a-consistent-rule-for-var-and-final-on-local-variables">DO follow a consistent rule for var and final on local variables</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-storing-what-you-can-calculate">AVOID storing what you can calculate</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#members">Members</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#dont-wrap-a-field-in-a-getter-and-setter-unnecessarily">DON'T wrap a field in a getter and setter unnecessarily</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-using-a-final-field-to-make-a-read-only-property">PREFER using a final field to make a read-only property</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-using-for-simple-members">CONSIDER using => for simple members</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-this-when-not-needed-to-avoid-shadowing">DON'T use this. except to redirect to a named constructor or to avoid shadowing</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-initialize-fields-at-their-declaration-when-possible">DO initialize fields at their declaration when possible</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#constructors">Constructors</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-initializing-formals-when-possible">DO use initializing formals when possible</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-late-when-a-constructor-initializer-list-will-do">DON'T use late when a constructor initializer list will do</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-instead-of-for-empty-constructor-bodies">DO use ; instead of {} for empty constructor bodies</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-new">DON'T use new</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-const-redundantly">DON'T use const redundantly</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#error-handling">Error handling</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-catches-without-on-clauses">AVOID catches without on clauses</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-discard-errors-from-catches-without-on-clauses">DON'T discard errors from catches without on clauses</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-throw-objects-that-implement-error-only-for-programmatic-errors">DO throw objects that implement Error only for programmatic errors</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-explicitly-catch-error-or-types-that-implement-it">DON'T explicitly catch Error or types that implement it</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-rethrow-to-rethrow-a-caught-exception">DO use rethrow to rethrow a caught exception</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#asynchrony">Asynchrony</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-asyncawait-over-using-raw-futures">PREFER async/await over using raw futures</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-async-when-it-has-no-useful-effect">DON'T use async when it has no useful effect</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-using-higher-order-methods-to-transform-a-stream">CONSIDER using higher-order methods to transform a stream</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-completer-directly">AVOID using Completer directly</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-test-for-futuret-when-disambiguating-a-futureort-whose-type-argument-could-be-object">DO test for Future<T> when disambiguating a FutureOr<T> whose type argument could be Object</a></li></ul></li></ul></div><article><div class="content"><div id="site-content-title"><h1>Effective Dart: Usage</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents keyboard_arrow_down keyboard_arrow_up</header><ul class="section-nav"><li class="toc-entry"><a href="#libraries">Libraries</a><ul><li class="toc-entry"><a href="#do-use-strings-in-part-of-directives">DO use strings in part of directives</a></li><li class="toc-entry"><a href="#dont-import-libraries-that-are-inside-the-src-directory-of-another-package">DON'T import libraries that are inside the src directory of another package</a></li><li class="toc-entry"><a href="#dont-allow-an-import-path-to-reach-into-or-out-of-lib">DON'T allow an import path to reach into or out of lib</a></li><li class="toc-entry"><a href="#prefer-relative-import-paths">PREFER relative import paths</a></li></ul></li><li class="toc-entry"><a href="#null">Null</a><ul><li class="toc-entry"><a href="#dont-explicitly-initialize-variables-to-null">DON'T explicitly initialize variables to null</a></li><li class="toc-entry"><a href="#dont-use-an-explicit-default-value-of-null">DON'T use an explicit default value of null</a></li><li class="toc-entry"><a href="#dont-use-true-or-false-in-equality-operations">DON'T use true or false in equality operations</a></li><li class="toc-entry"><a href="#avoid-late-variables-if-you-need-to-check-whether-they-are-initialized">AVOID late variables if you need to check whether they are initialized</a></li><li class="toc-entry"><a href="#consider-type-promotion-or-null-check-patterns-for-using-nullable-types">CONSIDER type promotion or null-check patterns for using nullable types</a></li></ul></li><li class="toc-entry"><a href="#strings">Strings</a><ul><li class="toc-entry"><a href="#do-use-adjacent-strings-to-concatenate-string-literals">DO use adjacent strings to concatenate string literals</a></li><li class="toc-entry"><a href="#prefer-using-interpolation-to-compose-strings-and-values">PREFER using interpolation to compose strings and values</a></li><li class="toc-entry"><a href="#avoid-using-curly-braces-in-interpolation-when-not-needed">AVOID using curly braces in interpolation when not needed</a></li></ul></li><li class="toc-entry"><a href="#collections">Collections</a><ul><li class="toc-entry"><a href="#do-use-collection-literals-when-possible">DO use collection literals when possible</a></li><li class="toc-entry"><a href="#dont-use-length-to-see-if-a-collection-is-empty">DON'T use .length to see if a collection is empty</a></li><li class="toc-entry"><a href="#avoid-using-iterable-foreach-with-a-function-literal">AVOID using Iterable.forEach() with a function literal</a></li><li class="toc-entry"><a href="#dont-use-list-from-unless-you-intend-to-change-the-type-of-the-result">DON'T use List.from() unless you intend to change the type of the result</a></li><li class="toc-entry"><a href="#do-use-wheretype-to-filter-a-collection-by-type">DO use whereType() to filter a collection by type</a></li><li class="toc-entry"><a href="#dont-use-cast-when-a-nearby-operation-will-do">DON'T use cast() when a nearby operation will do</a></li><li class="toc-entry"><a href="#avoid-using-cast">AVOID using cast()</a></li></ul></li><li class="toc-entry"><a href="#functions">Functions</a><ul><li class="toc-entry"><a href="#do-use-a-function-declaration-to-bind-a-function-to-a-name">DO use a function declaration to bind a function to a name</a></li><li class="toc-entry"><a href="#dont-create-a-lambda-when-a-tear-off-will-do">DON'T create a lambda when a tear-off will do</a></li></ul></li><li class="toc-entry"><a href="#variables">Variables</a><ul><li class="toc-entry"><a href="#do-follow-a-consistent-rule-for-var-and-final-on-local-variables">DO follow a consistent rule for var and final on local variables</a></li><li class="toc-entry"><a href="#avoid-storing-what-you-can-calculate">AVOID storing what you can calculate</a></li></ul></li><li class="toc-entry"><a href="#members">Members</a><ul><li class="toc-entry"><a href="#dont-wrap-a-field-in-a-getter-and-setter-unnecessarily">DON'T wrap a field in a getter and setter unnecessarily</a></li><li class="toc-entry"><a href="#prefer-using-a-final-field-to-make-a-read-only-property">PREFER using a final field to make a read-only property</a></li><li class="toc-entry"><a href="#consider-using-for-simple-members">CONSIDER using => for simple members</a></li><li class="toc-entry"><a href="#dont-use-this-when-not-needed-to-avoid-shadowing">DON'T use this. except to redirect to a named constructor or to avoid shadowing</a></li><li class="toc-entry"><a href="#do-initialize-fields-at-their-declaration-when-possible">DO initialize fields at their declaration when possible</a></li></ul></li><li class="toc-entry"><a href="#constructors">Constructors</a><ul><li class="toc-entry"><a href="#do-use-initializing-formals-when-possible">DO use initializing formals when possible</a></li><li class="toc-entry"><a href="#dont-use-late-when-a-constructor-initializer-list-will-do">DON'T use late when a constructor initializer list will do</a></li><li class="toc-entry"><a href="#do-use-instead-of-for-empty-constructor-bodies">DO use ; instead of {} for empty constructor bodies</a></li><li class="toc-entry"><a href="#dont-use-new">DON'T use new</a></li><li class="toc-entry"><a href="#dont-use-const-redundantly">DON'T use const redundantly</a></li></ul></li><li class="toc-entry"><a href="#error-handling">Error handling</a><ul><li class="toc-entry"><a href="#avoid-catches-without-on-clauses">AVOID catches without on clauses</a></li><li class="toc-entry"><a href="#dont-discard-errors-from-catches-without-on-clauses">DON'T discard errors from catches without on clauses</a></li><li class="toc-entry"><a href="#do-throw-objects-that-implement-error-only-for-programmatic-errors">DO throw objects that implement Error only for programmatic errors</a></li><li class="toc-entry"><a href="#dont-explicitly-catch-error-or-types-that-implement-it">DON'T explicitly catch Error or types that implement it</a></li><li class="toc-entry"><a href="#do-use-rethrow-to-rethrow-a-caught-exception">DO use rethrow to rethrow a caught exception</a></li></ul></li><li class="toc-entry"><a href="#asynchrony">Asynchrony</a><ul><li class="toc-entry"><a href="#prefer-asyncawait-over-using-raw-futures">PREFER async/await over using raw futures</a></li><li class="toc-entry"><a href="#dont-use-async-when-it-has-no-useful-effect">DON'T use async when it has no useful effect</a></li><li class="toc-entry"><a href="#consider-using-higher-order-methods-to-transform-a-stream">CONSIDER using higher-order methods to transform a stream</a></li><li class="toc-entry"><a href="#avoid-using-completer-directly">AVOID using Completer directly</a></li><li class="toc-entry"><a href="#do-test-for-futuret-when-disambiguating-a-futureort-whose-type-argument-could-be-object">DO test for Future<T> when disambiguating a FutureOr<T> whose type argument could be Object</a></li></ul></li></ul>more_horiz</div> <?code-excerpt plaster="none"?> <?code-excerpt replace="/([A-Z]\w*)\d\b/$1/g"?> <?code-excerpt path-base="misc/lib/effective_dart"?> You can use these guidelines every day in the bodies of your Dart code. Users of your library may not be able to tell that you've internalized the ideas here, but maintainers of it sure will.<div class="header-wrapper"><h2 id="libraries">Libraries</h2><a class="heading-link" href="#libraries" aria-label="Link to 'Libraries' section">#</a></div>These guidelines help you compose your program out of multiple files in a consistent, maintainable way. To keep these guidelines brief, they use "import" to cover <code>import</code> and <code>export</code> directives. The guidelines apply equally to both.<div class="header-wrapper"><h3 id="do-use-strings-in-part-of-directives">DO use strings in <code>part of</code> directives</h3><a class="heading-link" href="#do-use-strings-in-part-of-directives" aria-label="Link to 'DO use strings in part of directives' section">#</a></div>Linter rule: <a href="/tools/linter-rules/use_string_in_part_of_directives">use_string_in_part_of_directives</a>Many Dart developers avoid using <code>part</code> entirely. They find it easier to reason about their code when each library is a single file. If you do choose to use <code>part</code> to split part of a library out into another file, Dart requires the other file to in turn indicate which library it's a part of.Dart allows the <code>part of</code> directive to use the name of a library. Naming libraries is a legacy feature that is now <a href="/effective-dart/style#dont-explicitly-name-libraries">discouraged</a>. Library names can introduce ambiguity when determining which library a part belongs to.The preferred syntax is to use a URI string that points directly to the library file. If you have some library, <code>my_library.dart</code>, that contains: <?code-excerpt "my_library.dart" remove="ignore_for_file"?> <div class="code-block-wrapper language-dart"><div class="code-block-header">my_library.dart</div><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>library my_library; part 'some/other/file.dart';</code></pre></div></div>Then the part file should use the library file's URI string: <?code-excerpt "some/other/file.dart"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>part of '../../my_library.dart';</code></pre></div></div>Not the library name: <?code-excerpt "some/other/file_2.dart (part-of)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>part of my_library;</code></pre></div></div><div class="header-wrapper"><h3 id="dont-import-libraries-that-are-inside-the-src-directory-of-another-package">DON'T import libraries that are inside the <code>src</code> directory of another package</h3><a class="heading-link" href="#dont-import-libraries-that-are-inside-the-src-directory-of-another-package" aria-label="Link to 'DON'T import libraries that are inside the src directory of another package' section">#</a></div>Linter rule: <a href="/tools/linter-rules/implementation_imports">implementation_imports</a>The <code>src</code> directory under <code>lib</code> <a href="/tools/pub/package-layout">is specified</a> to contain libraries private to the package's own implementation. The way package maintainers version their package takes this convention into account. They are free to make sweeping changes to code under <code>src</code> without it being a breaking change to the package.That means that if you import some other package's private library, a minor, theoretically non-breaking point release of that package could break your code.<div class="header-wrapper"><h3 id="dont-allow-an-import-path-to-reach-into-or-out-of-lib">DON'T allow an import path to reach into or out of <code>lib</code></h3><a class="heading-link" href="#dont-allow-an-import-path-to-reach-into-or-out-of-lib" aria-label="Link to 'DON'T allow an import path to reach into or out of lib' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_relative_lib_imports">avoid_relative_lib_imports</a>A <code>package:</code> import lets you access a library inside a package's <code>lib</code> directory without having to worry about where the package is stored on your computer. For this to work, you cannot have imports that require the <code>lib</code> to be in some location on disk relative to other files. In other words, a relative import path in a file inside <code>lib</code> can't reach out and access a file outside of the <code>lib</code> directory, and a library outside of <code>lib</code> can't use a relative path to reach into the <code>lib</code> directory. Doing either leads to confusing errors and broken programs.For example, say your directory structure looks like this:<div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>my_package └─ lib └─ api.dart test └─ api_test.dart</code></pre></div></div>And say <code>api_test.dart</code> imports <code>api.dart</code> in two ways:<div class="code-block-wrapper language-dart"><div class="code-block-header">api_test.dart</div><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>import 'package:my_package/api.dart'; import '../lib/api.dart';</code></pre></div></div>Dart thinks those are imports of two completely unrelated libraries. To avoid confusing Dart and yourself, follow these two rules:<ul><li>Don't use <code>/lib/</code> in import paths.</li><li>Don't use <code>../</code> to escape the <code>lib</code> directory.</li></ul>Instead, when you need to reach into a package's <code>lib</code> directory (even from the same package's <code>test</code> directory or any other top-level directory), use a <code>package:</code> import.<div class="code-block-wrapper language-dart"><div class="code-block-header">api_test.dart</div><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>import 'package:my_package/api.dart';</code></pre></div></div>A package should never reach out of its <code>lib</code> directory and import libraries from other places in the package.<div class="header-wrapper"><h3 id="prefer-relative-import-paths">PREFER relative import paths</h3><a class="heading-link" href="#prefer-relative-import-paths" aria-label="Link to 'PREFER relative import paths' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_relative_imports">prefer_relative_imports</a>Whenever the previous rule doesn't come into play, follow this one. When an import does not reach across <code>lib</code>, prefer using relative imports. They're shorter. For example, say your directory structure looks like this:<div class="code-block-wrapper language-plaintext"><div class="code-block-body"><pre class="shiki dash-light" tabindex="0"><code>my_package └─ lib ├─ src │ └─ stuff.dart │ └─ utils.dart └─ api.dart test │─ api_test.dart └─ test_utils.dart</code></pre></div></div>Here is how the various libraries should import each other:<div class="code-block-wrapper language-dart"><div class="code-block-header">lib/api.dart</div><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>import 'src/stuff.dart'; import 'src/utils.dart';</code></pre></div></div><div class="code-block-wrapper language-dart"><div class="code-block-header">lib/src/utils.dart</div><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>import '../api.dart'; import 'stuff.dart';</code></pre></div></div><div class="code-block-wrapper language-dart"><div class="code-block-header">test/api_test.dart</div><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>import 'package:my_package/api.dart'; // Don't reach into 'lib'. import 'test_utils.dart'; // Relative within 'test' is fine.</code></pre></div></div><div class="header-wrapper"><h2 id="null">Null</h2><a class="heading-link" href="#null" aria-label="Link to 'Null' section">#</a></div><div class="header-wrapper"><h3 id="dont-explicitly-initialize-variables-to-null">DON'T explicitly initialize variables to <code>null</code></h3><a class="heading-link" href="#dont-explicitly-initialize-variables-to-null" aria-label="Link to 'DON'T explicitly initialize variables to null' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_init_to_null">avoid_init_to_null</a>If a variable has a non-nullable type, Dart reports a compile error if you try to use it before it has been definitely initialized. If the variable is nullable, then it is implicitly initialized to <code>null</code> for you. There's no concept of "uninitialized memory" in Dart and no need to explicitly initialize a variable to <code>null</code> to be "safe". <?code-excerpt "usage_good.dart (no-null-init)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Item? bestDeal(List<Item> cart) { Item? bestItem; for (final item in cart) { if (bestItem == null || item.price < bestItem.price) { bestItem = item; } } return bestItem; }</code></pre></div></div><?code-excerpt "usage_bad.dart (no-null-init)" replace="/ = null/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Item? bestDeal(List<Item> cart) { Item? bestItem = null; for (final item in cart) { if (bestItem == null || item.price < bestItem.price) { bestItem = item; } } return bestItem; }</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-an-explicit-default-value-of-null">DON'T use an explicit default value of <code>null</code></h3><a class="heading-link" href="#dont-use-an-explicit-default-value-of-null" aria-label="Link to 'DON'T use an explicit default value of null' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_init_to_null">avoid_init_to_null</a>If you make a nullable parameter optional but don't give it a default value, the language implicitly uses <code>null</code> as the default, so there's no need to write it. <?code-excerpt "usage_good.dart (default-value-null)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>void error([String? message]) { stderr.write(message ?? '\n'); }</code></pre></div></div><?code-excerpt "usage_bad.dart (default-value-null)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>void error([String? message = null]) { stderr.write(message ?? '\n'); }</code></pre></div></div><a id="prefer-using--to-convert-null-to-a-boolean-value"></a><div class="header-wrapper"><h3 id="dont-use-true-or-false-in-equality-operations">DON'T use <code>true</code> or <code>false</code> in equality operations</h3><a class="heading-link" href="#dont-use-true-or-false-in-equality-operations" aria-label="Link to 'DON'T use true or false in equality operations' section">#</a></div>Using the equality operator to evaluate a non-nullable boolean expression against a boolean literal is redundant. It's always simpler to eliminate the equality operator, and use the unary negation operator <code>!</code> if necessary: <?code-excerpt "usage_good.dart (non-null-boolean-expression)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>if (nonNullableBool) { ... } if (!nonNullableBool) { ... }</code></pre></div></div><?code-excerpt "usage_bad.dart (non-null-boolean-expression)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>if (nonNullableBool == true) { ... } if (nonNullableBool == false) { ... }</code></pre></div></div>To evaluate a boolean expression that is nullable, you should use <code>??</code> or an explicit <code>!= null</code> check. <?code-excerpt "usage_good.dart (nullable-boolean-expression)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>// If you want null to result in false: if (nullableBool ?? false) { ... } // If you want null to result in false // and you want the variable to type promote: if (nullableBool != null && nullableBool) { ... }</code></pre></div></div><?code-excerpt "usage_bad.dart (nullable-boolean-expression)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>// Static error if null: if (nullableBool) { ... } // If you want null to be false: if (nullableBool == true) { ... }</code></pre></div></div><code>nullableBool == true</code> is a viable expression, but shouldn't be used for several reasons:<ul><li>It doesn't indicate the code has anything to do with <code>null</code>.</li><li>Because it's not evidently <code>null</code> related, it can easily be mistaken for the non-nullable case, where the equality operator is redundant and can be removed. That's only true when the boolean expression on the left has no chance of producing null, but not when it can.</li><li>The boolean logic is confusing. If <code>nullableBool</code> is null, then <code>nullableBool == true</code> means the condition evaluates to <code>false</code>.</li></ul>The <code>??</code> operator makes it clear that something to do with null is happening, so it won't be mistaken for a redundant operation. The logic is much clearer too; the result of the expression being <code>null</code> is the same as the boolean literal.Using a null-aware operator such as <code>??</code> on a variable inside a condition doesn't promote the variable to a non-nullable type. If you want the variable to be promoted inside the body of the <code>if</code> statement, it's better to use an explicit <code>!= null</code> check instead of <code>??</code>.<div class="header-wrapper"><h3 id="avoid-late-variables-if-you-need-to-check-whether-they-are-initialized">AVOID <code>late</code> variables if you need to check whether they are initialized</h3><a class="heading-link" href="#avoid-late-variables-if-you-need-to-check-whether-they-are-initialized" aria-label="Link to 'AVOID late variables if you need to check whether they are initialized' section">#</a></div>Dart offers no way to tell if a <code>late</code> variable has been initialized or assigned to. If you access it, it either immediately runs the initializer (if it has one) or throws an exception. Sometimes you have some state that's lazily initialized where <code>late</code> might be a good fit, but you also need to be able to tell if the initialization has happened yet.Although you could detect initialization by storing the state in a <code>late</code> variable and having a separate boolean field that tracks whether the variable has been set, that's redundant because Dart internally maintains the initialized status of the <code>late</code> variable. Instead, it's usually clearer to make the variable non-<code>late</code> and nullable. Then you can see if the variable has been initialized by checking for <code>null</code>.Of course, if <code>null</code> is a valid initialized value for the variable, then it probably does make sense to have a separate boolean field.<div class="header-wrapper"><h3 id="consider-type-promotion-or-null-check-patterns-for-using-nullable-types">CONSIDER type promotion or null-check patterns for using nullable types</h3><a class="heading-link" href="#consider-type-promotion-or-null-check-patterns-for-using-nullable-types" aria-label="Link to 'CONSIDER type promotion or null-check patterns for using nullable types' section">#</a></div>Checking that a nullable variable is not equal to <code>null</code> promotes the variable to a non-nullable type. That lets you access members on the variable and pass it to functions expecting a non-nullable type.Type promotion is only supported, however, for local variables, parameters, and private final fields. Values that are open to manipulation <a href="/tools/non-promotion-reasons">can't be type promoted</a>.Declaring members <a href="/effective-dart/design#prefer-making-declarations-private">private</a> and <a href="/effective-dart/design#prefer-making-fields-and-top-level-variables-final">final</a>, as we generally recommend, is often enough to bypass these limitations. But, that's not always an option.One pattern to work around type promotion limitations is to use a <a href="/language/pattern-types#null-check">null-check pattern</a>. This simultaneously confirms the member's value is not null, and binds that value to a new non-nullable variable of the same base type. <?code-excerpt "usage_good.dart (null-check-promo)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class UploadException { final Response? response; UploadException([this.response]); @override String toString() { if (this.response case var response?) { return 'Could not complete upload to ${response.url} ' '(error code ${response.errorCode}): ${response.reason}.'; } return 'Could not upload (no response).'; } }</code></pre></div></div>Another work around is to assign the field's value to a local variable. Null checks on that variable will promote, so you can safely treat it as non-nullable. <?code-excerpt "usage_good.dart (shadow-nullable-field)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class UploadException { final Response? response; UploadException([this.response]); @override String toString() { final response = this.response; if (response != null) { return 'Could not complete upload to ${response.url} ' '(error code ${response.errorCode}): ${response.reason}.'; } return 'Could not upload (no response).'; } }</code></pre></div></div>Be careful when using a local variable. If you need to write back to the field, make sure that you don't write back to the local variable instead. (Making the local variable <a href="/effective-dart/usage#do-follow-a-consistent-rule-for-var-and-final-on-local-variables"><code>final</code></a> can prevent such mistakes.) Also, if the field might change while the local is still in scope, then the local might have a stale value.Sometimes it's best to simply <a href="/null-safety/understanding-null-safety#non-null-assertion-operator">use <code>!</code></a> on the field. In some cases, though, using either a local variable or a null-check pattern can be cleaner and safer than using <code>!</code> every time you need to treat the value as non-null: <?code-excerpt "usage_bad.dart (shadow-nullable-field)" replace="/!\./[!!!]./g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class UploadException { final Response? response; UploadException([this.response]); @override String toString() { if (response != null) { return 'Could not complete upload to ${response!.url} ' '(error code ${response!.errorCode}): ${response!.reason}.'; } return 'Could not upload (no response).'; } }</code></pre></div></div><div class="header-wrapper"><h2 id="strings">Strings</h2><a class="heading-link" href="#strings" aria-label="Link to 'Strings' section">#</a></div>Here are some best practices to keep in mind when composing strings in Dart.<div class="header-wrapper"><h3 id="do-use-adjacent-strings-to-concatenate-string-literals">DO use adjacent strings to concatenate string literals</h3><a class="heading-link" href="#do-use-adjacent-strings-to-concatenate-string-literals" aria-label="Link to 'DO use adjacent strings to concatenate string literals' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_adjacent_string_concatenation">prefer_adjacent_string_concatenation</a>If you have two string literals—not values, but the actual quoted literal form—you do not need to use <code>+</code> to concatenate them. Just like in C and C++, simply placing them next to each other does it. This is a good way to make a single long string that doesn't fit on one line. <?code-excerpt "usage_good.dart (adjacent-strings-literals)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>raiseAlarm( 'ERROR: Parts of the spaceship are on fire. Other ' 'parts are overrun by martians. Unclear which are which.', );</code></pre></div></div><?code-excerpt "usage_bad.dart (adjacent-strings-literals)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>raiseAlarm( 'ERROR: Parts of the spaceship are on fire. Other ' + 'parts are overrun by martians. Unclear which are which.', );</code></pre></div></div><div class="header-wrapper"><h3 id="prefer-using-interpolation-to-compose-strings-and-values">PREFER using interpolation to compose strings and values</h3><a class="heading-link" href="#prefer-using-interpolation-to-compose-strings-and-values" aria-label="Link to 'PREFER using interpolation to compose strings and values' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_interpolation_to_compose_strings">prefer_interpolation_to_compose_strings</a>If you're coming from other languages, you're used to using long chains of <code>+</code> to build a string out of literals and other values. That does work in Dart, but it's almost always cleaner and shorter to use interpolation: <?code-excerpt "usage_good.dart (string-interpolation)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>'Hello, $name! You are ${year - birth} years old.';</code></pre></div></div><?code-excerpt "usage_bad.dart (string-interpolation)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>'Hello, ' + name + '! You are ' + (year - birth).toString() + ' y...';</code></pre></div></div>Note that this guideline applies to combining multiple literals and values. It's fine to use <code>.toString()</code> when converting only a single object to a string.<div class="header-wrapper"><h3 id="avoid-using-curly-braces-in-interpolation-when-not-needed">AVOID using curly braces in interpolation when not needed</h3><a class="heading-link" href="#avoid-using-curly-braces-in-interpolation-when-not-needed" aria-label="Link to 'AVOID using curly braces in interpolation when not needed' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_brace_in_string_interps">unnecessary_brace_in_string_interps</a>If you're interpolating a simple identifier not immediately followed by more alphanumeric text, the <code>{}</code> should be omitted. <?code-excerpt "usage_good.dart (string-interpolation-avoid-curly)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var greeting = 'Hi, $name! I love your ${decade}s costume.';</code></pre></div></div><?code-excerpt "usage_bad.dart (string-interpolation-avoid-curly)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var greeting = 'Hi, ${name}! I love your ${decade}s costume.';</code></pre></div></div><div class="header-wrapper"><h2 id="collections">Collections</h2><a class="heading-link" href="#collections" aria-label="Link to 'Collections' section">#</a></div>Out of the box, Dart supports four collection types: lists, maps, queues, and sets. The following best practices apply to collections.<div class="header-wrapper"><h3 id="do-use-collection-literals-when-possible">DO use collection literals when possible</h3><a class="heading-link" href="#do-use-collection-literals-when-possible" aria-label="Link to 'DO use collection literals when possible' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_collection_literals">prefer_collection_literals</a>Dart has three core collection types: List, Map, and Set. The Map and Set classes have unnamed constructors like most classes do. But because these collections are used so frequently, Dart has nicer built-in syntax for creating them: <?code-excerpt "usage_good.dart (collection-literals)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var points = <Point>[]; var addresses = <String, Address>{}; var counts = <int>{};</code></pre></div></div><?code-excerpt "usage_bad.dart (collection-literals)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var addresses = Map<String, Address>(); var counts = Set<int>();</code></pre></div></div>Note that this guideline doesn't apply to the named constructors for those classes. <code>List.from()</code>, <code>Map.fromIterable()</code>, and friends all have their uses. (The List class also has an unnamed constructor, but it is prohibited in null safe Dart.)Collection literals are particularly powerful in Dart because they give you access to the <a href="/language/collections#spread-operators">spread operator</a> for including the contents of other collections, and <a href="/language/collections#control-flow-operators"><code>if</code> and <code>for</code></a> for performing control flow while building the contents: <?code-excerpt "usage_good.dart (spread-etc)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var arguments = [ ...options, command, ...?modeFlags, for (var path in filePaths) if (path.endsWith('.dart')) path.replaceAll('.dart', '.js'), ];</code></pre></div></div><?code-excerpt "usage_bad.dart (spread-etc)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var arguments = <String>[]; arguments.addAll(options); arguments.add(command); if (modeFlags != null) arguments.addAll(modeFlags); arguments.addAll( filePaths .where((path) => path.endsWith('.dart')) .map((path) => path.replaceAll('.dart', '.js')), );</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-length-to-see-if-a-collection-is-empty">DON'T use <code>.length</code> to see if a collection is empty</h3><a class="heading-link" href="#dont-use-length-to-see-if-a-collection-is-empty" aria-label="Link to 'DON'T use .length to see if a collection is empty' section">#</a></div>Linter rules: <a href="/tools/linter-rules/prefer_is_empty">prefer_is_empty</a>, <a href="/tools/linter-rules/prefer_is_not_empty">prefer_is_not_empty</a>The <a href="https://api.dart.dev/dart-core/Iterable-class.html">Iterable</a> contract does not require that a collection know its length or be able to provide it in constant time. Calling <code>.length</code> just to see if the collection contains anything can be painfully slow.Instead, there are faster and more readable getters: <code>.isEmpty</code> and <code>.isNotEmpty</code>. Use the one that doesn't require you to negate the result. <?code-excerpt "usage_good.dart (dont-use-length)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>if (lunchBox.isEmpty) return 'so hungry...'; if (words.isNotEmpty) return words.join(' ');</code></pre></div></div><?code-excerpt "usage_bad.dart (dont-use-length)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>if (lunchBox.length == 0) return 'so hungry...'; if (!words.isEmpty) return words.join(' ');</code></pre></div></div><div class="header-wrapper"><h3 id="avoid-using-iterable-foreach-with-a-function-literal">AVOID using <code>Iterable.forEach()</code> with a function literal</h3><a class="heading-link" href="#avoid-using-iterable-foreach-with-a-function-literal" aria-label="Link to 'AVOID using Iterable.forEach() with a function literal' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_function_literals_in_foreach_calls">avoid_function_literals_in_foreach_calls</a><code>forEach()</code> functions are widely used in JavaScript because the built in <code>for-in</code> loop doesn't do what you usually want. In Dart, if you want to iterate over a sequence, the idiomatic way to do that is using a loop. <?code-excerpt "usage_good.dart (avoid-for-each)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>for (final person in people) { ... }</code></pre></div></div><?code-excerpt "usage_bad.dart (avoid-for-each)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>people.forEach((person) { ... });</code></pre></div></div>Note that this guideline specifically says "function literal". If you want to invoke some already existing function on each element, <code>forEach()</code> is fine. <?code-excerpt "usage_good.dart (forEach-over-func)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>people.forEach(print);</code></pre></div></div>Also note that it's always OK to use <code>Map.forEach()</code>. Maps aren't iterable, so this guideline doesn't apply.<div class="header-wrapper"><h3 id="dont-use-list-from-unless-you-intend-to-change-the-type-of-the-result">DON'T use <code>List.from()</code> unless you intend to change the type of the result</h3><a class="heading-link" href="#dont-use-list-from-unless-you-intend-to-change-the-type-of-the-result" aria-label="Link to 'DON'T use List.from() unless you intend to change the type of the result' section">#</a></div>Given an Iterable, there are two obvious ways to produce a new List that contains the same elements: <?code-excerpt "../../test/effective_dart_test.dart (list-from-1)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body">dart<pre class="shiki dash-light" tabindex="0"><code>var copy1 = iterable.toList(); var copy2 = List.from(iterable);</code></pre></div></div>The obvious difference is that the first one is shorter. The important difference is that the first one preserves the type argument of the original object: <?code-excerpt "../../test/effective_dart_test.dart (list-from-good)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>// Creates a List<int>: var iterable = [1, 2, 3]; // Prints "List<int>": print(iterable.toList().runtimeType);</code></pre></div></div><?code-excerpt "../../test/effective_dart_test.dart (list-from-bad)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>// Creates a List<int>: var iterable = [1, 2, 3]; // Prints "List<dynamic>": print(List.from(iterable).runtimeType);</code></pre></div></div>If you want to change the type, then calling <code>List.from()</code> is useful: <?code-excerpt "../../test/effective_dart_test.dart (list-from-3)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var numbers = [1, 2.3, 4]; // List<num>. numbers.removeAt(1); // Now it only contains integers. var ints = List<int>.from(numbers);</code></pre></div></div>But if your goal is just to copy the iterable and preserve its original type, or you don't care about the type, then use <code>toList()</code>.<div class="header-wrapper"><h3 id="do-use-wheretype-to-filter-a-collection-by-type">DO use <code>whereType()</code> to filter a collection by type</h3><a class="heading-link" href="#do-use-wheretype-to-filter-a-collection-by-type" aria-label="Link to 'DO use whereType() to filter a collection by type' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_iterable_whereType">prefer_iterable_whereType</a>Let's say you have a list containing a mixture of objects, and you want to get just the integers out of it. You could use <code>where()</code> like this: <?code-excerpt "usage_bad.dart (where-type)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var objects = [1, 'a', 2, 'b', 3]; var ints = objects.where((e) => e is int);</code></pre></div></div>This is verbose, but, worse, it returns an iterable whose type probably isn't what you want. In the example here, it returns an <code>Iterable<Object></code> even though you likely want an <code>Iterable<int></code> since that's the type you're filtering it to.Sometimes you see code that "corrects" the above error by adding <code>cast()</code>: <?code-excerpt "usage_bad.dart (where-type-2)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var objects = [1, 'a', 2, 'b', 3]; var ints = objects.where((e) => e is int).cast<int>();</code></pre></div></div>That's verbose and causes two wrappers to be created, with two layers of indirection and redundant runtime checking. Fortunately, the core library has the <a href="https://api.dart.dev/dart-core/Iterable/whereType.html"><code>whereType()</code></a> method for this exact use case: <?code-excerpt "../../test/effective_dart_test.dart (where-type)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var objects = [1, 'a', 2, 'b', 3]; var ints = objects.whereType<int>();</code></pre></div></div>Using <code>whereType()</code> is concise, produces an <a href="https://api.dart.dev/dart-core/Iterable-class.html">Iterable</a> of the desired type, and has no unnecessary levels of wrapping.<div class="header-wrapper"><h3 id="dont-use-cast-when-a-nearby-operation-will-do">DON'T use <code>cast()</code> when a nearby operation will do</h3><a class="heading-link" href="#dont-use-cast-when-a-nearby-operation-will-do" aria-label="Link to 'DON'T use cast() when a nearby operation will do' section">#</a></div>Often when you're dealing with an iterable or stream, you perform several transformations on it. At the end, you want to produce an object with a certain type argument. Instead of tacking on a call to <code>cast()</code>, see if one of the existing transformations can change the type.If you're already calling <code>toList()</code>, replace that with a call to <a href="https://api.dart.dev/dart-core/List/List.from.html"><code>List<T>.from()</code></a> where <code>T</code> is the type of resulting list you want. <?code-excerpt "usage_good.dart (cast-list)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var stuff = <dynamic>[1, 2]; var ints = List<int>.from(stuff);</code></pre></div></div><?code-excerpt "usage_bad.dart (cast-list)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var stuff = <dynamic>[1, 2]; var ints = stuff.toList().cast<int>();</code></pre></div></div>If you are calling <code>map()</code>, give it an explicit type argument so that it produces an iterable of the desired type. Type inference often picks the correct type for you based on the function you pass to <code>map()</code>, but sometimes you need to be explicit. <?code-excerpt "usage_good.dart (cast-map)" replace="/$n as int$/n/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var stuff = <dynamic>[1, 2]; var reciprocals = stuff.map<double>((n) => 1 / n);</code></pre></div></div><?code-excerpt "usage_bad.dart (cast-map)" replace="/$n as int$/n/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var stuff = <dynamic>[1, 2]; var reciprocals = stuff.map((n) => 1 / n).cast<double>();</code></pre></div></div><div class="header-wrapper"><h3 id="avoid-using-cast">AVOID using <code>cast()</code></h3><a class="heading-link" href="#avoid-using-cast" aria-label="Link to 'AVOID using cast()' section">#</a></div>This is the softer generalization of the previous rule. Sometimes there is no nearby operation you can use to fix the type of some object. Even then, when possible avoid using <code>cast()</code> to "change" a collection's type.Prefer any of these options instead:<ul><li>Create it with the right type. Change the code where the collection is first created so that it has the right type.</li><li>Cast the elements on access. If you immediately iterate over the collection, cast each element inside the iteration.</li><li>Eagerly cast using <code>List.from()</code>. If you'll eventually access most of the elements in the collection, and you don't need the object to be backed by the original live object, convert it using <code>List.from()</code>.The <code>cast()</code> method returns a lazy collection that checks the element type on every operation. If you perform only a few operations on only a few elements, that laziness can be good. But in many cases, the overhead of lazy validation and of wrapping outweighs the benefits.</li></ul>Here is an example of creating it with the right type: <?code-excerpt "usage_good.dart (cast-at-create)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>List<int> singletonList(int value) { var list = <int>[]; list.add(value); return list; }</code></pre></div></div><?code-excerpt "usage_bad.dart (cast-at-create)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>List<int> singletonList(int value) { var list = []; // List<dynamic>. list.add(value); return list.cast<int>(); }</code></pre></div></div>Here is casting each element on access: <?code-excerpt "usage_good.dart (cast-iterate)" replace="/$n as int$/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>void printEvens(List<Object> objects) { // We happen to know the list only contains ints. for (final n in objects) { if ((n as int).isEven) print(n); } }</code></pre></div></div><?code-excerpt "usage_bad.dart (cast-iterate)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>void printEvens(List<Object> objects) { // We happen to know the list only contains ints. for (final n in objects.cast<int>()) { if (n.isEven) print(n); } }</code></pre></div></div>Here is casting eagerly using <code>List.from()</code>: <?code-excerpt "usage_good.dart (cast-from)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>int median(List<Object> objects) { // We happen to know the list only contains ints. var ints = List<int>.from(objects); ints.sort(); return ints[ints.length ~/ 2]; }</code></pre></div></div><?code-excerpt "usage_bad.dart (cast-from)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>int median(List<Object> objects) { // We happen to know the list only contains ints. var ints = objects.cast<int>(); ints.sort(); return ints[ints.length ~/ 2]; }</code></pre></div></div>These alternatives don't always work, of course, and sometimes <code>cast()</code> is the right answer. But consider that method a little risky and undesirable—it can be slow and may fail at runtime if you aren't careful.<div class="header-wrapper"><h2 id="functions">Functions</h2><a class="heading-link" href="#functions" aria-label="Link to 'Functions' section">#</a></div>In Dart, even functions are objects. Here are some best practices involving functions.<div class="header-wrapper"><h3 id="do-use-a-function-declaration-to-bind-a-function-to-a-name">DO use a function declaration to bind a function to a name</h3><a class="heading-link" href="#do-use-a-function-declaration-to-bind-a-function-to-a-name" aria-label="Link to 'DO use a function declaration to bind a function to a name' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_function_declarations_over_variables">prefer_function_declarations_over_variables</a>Modern languages have realized how useful local nested functions and closures are. It's common to have a function defined inside another one. In many cases, this function is used as a callback immediately and doesn't need a name. A function expression is great for that.But, if you do need to give it a name, use a function declaration statement instead of binding a lambda to a variable. <?code-excerpt "usage_good.dart (func-decl)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>void main() { void localFunction() { ... } }</code></pre></div></div><?code-excerpt "usage_bad.dart (func-decl)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>void main() { var localFunction = () { ... }; }</code></pre></div></div><div class="header-wrapper"><h3 id="dont-create-a-lambda-when-a-tear-off-will-do">DON'T create a lambda when a tear-off will do</h3><a class="heading-link" href="#dont-create-a-lambda-when-a-tear-off-will-do" aria-label="Link to 'DON'T create a lambda when a tear-off will do' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_lambdas">unnecessary_lambdas</a>When you refer to a function, method, or named constructor without parentheses, Dart creates a tear-off. This is a closure that takes the same parameters as the function and invokes the underlying function when you call it. If your code needs a closure that invokes a named function with the same parameters as the closure accepts, don't wrap the call in a lambda. Use a tear-off. <?code-excerpt "usage_good.dart (use-tear-off)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>var charCodes = [68, 97, 114, 116]; var buffer = StringBuffer(); // Function: charCodes.forEach(print); // Method: charCodes.forEach(buffer.write); // Named constructor: var strings = charCodes.map(String.fromCharCode); // Unnamed constructor: var buffers = charCodes.map(StringBuffer.new);</code></pre></div></div><?code-excerpt "usage_bad.dart (use-tear-off)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>var charCodes = [68, 97, 114, 116]; var buffer = StringBuffer(); // Function: charCodes.forEach((code) { print(code); }); // Method: charCodes.forEach((code) { buffer.write(code); }); // Named constructor: var strings = charCodes.map((code) => String.fromCharCode(code)); // Unnamed constructor: var buffers = charCodes.map((code) => StringBuffer(code));</code></pre></div></div><div class="header-wrapper"><h2 id="variables">Variables</h2><a class="heading-link" href="#variables" aria-label="Link to 'Variables' section">#</a></div>The following best practices describe how to best use variables in Dart.<div class="header-wrapper"><h3 id="do-follow-a-consistent-rule-for-var-and-final-on-local-variables">DO follow a consistent rule for <code>var</code> and <code>final</code> on local variables</h3><a class="heading-link" href="#do-follow-a-consistent-rule-for-var-and-final-on-local-variables" aria-label="Link to 'DO follow a consistent rule for var and final on local variables' section">#</a></div>Most local variables shouldn't have type annotations and should be declared using just <code>var</code> or <code>final</code>. There are two rules in wide use for when to use one or the other:<ul><li>Use <code>final</code> for local variables that are not reassigned and <code>var</code> for those that are.</li><li>Use <code>var</code> for all local variables, even ones that aren't reassigned. Never use <code>final</code> for locals. (Using <code>final</code> for fields and top-level variables is still encouraged, of course.)</li></ul>Either rule is acceptable, but pick one and apply it consistently throughout your code. That way when a reader sees <code>var</code>, they know whether it means that the variable is assigned later in the function.<div class="header-wrapper"><h3 id="avoid-storing-what-you-can-calculate">AVOID storing what you can calculate</h3><a class="heading-link" href="#avoid-storing-what-you-can-calculate" aria-label="Link to 'AVOID storing what you can calculate' section">#</a></div>When designing a class, you often want to expose multiple views into the same underlying state. Often you see code that calculates all of those views in the constructor and then stores them: <?code-excerpt "usage_bad.dart (calc-vs-store1)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Circle { double radius; double area; double circumference; Circle(double radius) : radius = radius, area = pi * radius * radius, circumference = pi * 2.0 * radius; }</code></pre></div></div>This code has two things wrong with it. First, it's likely wasting memory. The area and circumference, strictly speaking, are caches. They are stored calculations that we could recalculate from other data we already have. They are trading increased memory for reduced CPU usage. Do we know we have a performance problem that merits that trade-off?Worse, the code is wrong. The problem with caches is invalidation—how do you know when the cache is out of date and needs to be recalculated? Here, we never do, even though <code>radius</code> is mutable. You can assign a different value and the <code>area</code> and <code>circumference</code> will retain their previous, now incorrect values.To correctly handle cache invalidation, we would need to do this: <?code-excerpt "usage_bad.dart (calc-vs-store2)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Circle { double _radius; double get radius => _radius; set radius(double value) { _radius = value; _recalculate(); } double _area = 0.0; double get area => _area; double _circumference = 0.0; double get circumference => _circumference; Circle(this._radius) { _recalculate(); } void _recalculate() { _area = pi * _radius * _radius; _circumference = pi * 2.0 * _radius; } }</code></pre></div></div>That's an awful lot of code to write, maintain, debug, and read. Instead, your first implementation should be: <?code-excerpt "usage_good.dart (calc-vs-store)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Circle { double radius; Circle(this.radius); double get area => pi * radius * radius; double get circumference => pi * 2.0 * radius; }</code></pre></div></div>This code is shorter, uses less memory, and is less error-prone. It stores the minimal amount of data needed to represent the circle. There are no fields to get out of sync because there is only a single source of truth.In some cases, you may need to cache the result of a slow calculation, but only do that after you know you have a performance problem, do it carefully, and leave a comment explaining the optimization.<div class="header-wrapper"><h2 id="members">Members</h2><a class="heading-link" href="#members" aria-label="Link to 'Members' section">#</a></div>In Dart, objects have members which can be functions (methods) or data (instance variables). The following best practices apply to an object's members.<div class="header-wrapper"><h3 id="dont-wrap-a-field-in-a-getter-and-setter-unnecessarily">DON'T wrap a field in a getter and setter unnecessarily</h3><a class="heading-link" href="#dont-wrap-a-field-in-a-getter-and-setter-unnecessarily" aria-label="Link to 'DON'T wrap a field in a getter and setter unnecessarily' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_getters_setters">unnecessary_getters_setters</a>In Java and C#, it's common to hide all fields behind getters and setters (or properties in C#), even if the implementation just forwards to the field. That way, if you ever need to do more work in those members, you can without needing to touch the call sites. This is because calling a getter method is different than accessing a field in Java, and accessing a property isn't binary-compatible with accessing a raw field in C#.Dart doesn't have this limitation. Fields and getters/setters are completely indistinguishable. You can expose a field in a class and later wrap it in a getter and setter without having to touch any code that uses that field. <?code-excerpt "usage_good.dart (dont-wrap-field)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Box { Object? contents; }</code></pre></div></div><?code-excerpt "usage_bad.dart (dont-wrap-field)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Box { Object? _contents; Object? get contents => _contents; set contents(Object? value) { _contents = value; } }</code></pre></div></div><div class="header-wrapper"><h3 id="prefer-using-a-final-field-to-make-a-read-only-property">PREFER using a <code>final</code> field to make a read-only property</h3><a class="heading-link" href="#prefer-using-a-final-field-to-make-a-read-only-property" aria-label="Link to 'PREFER using a final field to make a read-only property' section">#</a></div>If you have a field that outside code should be able to see but not assign to, a simple solution that works in many cases is to simply mark it <code>final</code>. <?code-excerpt "usage_good.dart (final)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Box { final contents = []; }</code></pre></div></div><?code-excerpt "usage_bad.dart (final)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Box { Object? _contents; Object? get contents => _contents; }</code></pre></div></div>Of course, if you need to internally assign to the field outside of the constructor, you may need to do the "private field, public getter" pattern, but don't reach for that until you need to.<div class="header-wrapper"><h3 id="consider-using-for-simple-members">CONSIDER using <code>=></code> for simple members</h3><a class="heading-link" href="#consider-using-for-simple-members" aria-label="Link to 'CONSIDER using => for simple members' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_expression_function_bodies">prefer_expression_function_bodies</a>In addition to using <code>=></code> for function expressions, Dart also lets you define members with it. That style is a good fit for simple members that just calculate and return a value. <?code-excerpt "usage_good.dart (use-arrow)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>double get area => (right - left) * (bottom - top); String capitalize(String name) => '${name[0].toUpperCase()}${name.substring(1)}';</code></pre></div></div>People writing code seem to love <code>=></code>, but it's very easy to abuse it and end up with code that's hard to read. If your declaration is more than a couple of lines or contains deeply nested expressions—cascades and conditional operators are common offenders—do yourself and everyone who has to read your code a favor and use a block body and some statements. <?code-excerpt "usage_good.dart (arrow-long)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Treasure? openChest(Chest chest, Point where) { if (_opened.containsKey(chest)) return null; var treasure = Treasure(where); treasure.addAll(chest.contents); _opened[chest] = treasure; return treasure; }</code></pre></div></div><?code-excerpt "usage_bad.dart (arrow-long)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Treasure? openChest(Chest chest, Point where) => _opened.containsKey(chest) ? null : _opened[chest] = (Treasure(where)..addAll(chest.contents));</code></pre></div></div>You can also use <code>=></code> on members that don't return a value. This is idiomatic when a setter is small and has a corresponding getter that uses <code>=></code>. <?code-excerpt "usage_good.dart (arrow-setter)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>num get x => center.x; set x(num value) => center = Point(value, center.y);</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-this-when-not-needed-to-avoid-shadowing">DON'T use <code>this.</code> except to redirect to a named constructor or to avoid shadowing</h3><a class="heading-link" href="#dont-use-this-when-not-needed-to-avoid-shadowing" aria-label="Link to 'DON'T use this. except to redirect to a named constructor or to avoid shadowing' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_this">unnecessary_this</a>JavaScript requires an explicit <code>this.</code> to refer to members on the object whose method is currently being executed, but Dart—like C++, Java, and C#—doesn't have that limitation.There are only two times you need to use <code>this.</code>. One is when a local variable with the same name shadows the member you want to access: <?code-excerpt "usage_bad.dart (this-dot)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Box { Object? value; void clear() { this.update(null); } void update(Object? value) { this.value = value; } }</code></pre></div></div><?code-excerpt "usage_good.dart (this-dot)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Box { Object? value; void clear() { update(null); } void update(Object? value) { this.value = value; } }</code></pre></div></div>The other time to use <code>this.</code> is when redirecting to a named constructor: <?code-excerpt "usage_bad.dart (this-dot-constructor)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class ShadeOfGray { final int brightness; ShadeOfGray(int val) : brightness = val; ShadeOfGray.black() : this(0); // This won't parse or compile! // ShadeOfGray.alsoBlack() : black(); }</code></pre></div></div><?code-excerpt "usage_good.dart (this-dot-constructor)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class ShadeOfGray { final int brightness; ShadeOfGray(int val) : brightness = val; ShadeOfGray.black() : this(0); // But now it will! ShadeOfGray.alsoBlack() : this.black(); }</code></pre></div></div>Note that constructor parameters never shadow fields in constructor initializer lists: <?code-excerpt "usage_good.dart (param-dont-shadow-field-ctr-init)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Box extends BaseBox { Object? value; Box(Object? value) : value = value, super(value); }</code></pre></div></div>This looks surprising, but works like you want. Fortunately, code like this is relatively rare thanks to initializing formals and super initializers.<div class="header-wrapper"><h3 id="do-initialize-fields-at-their-declaration-when-possible">DO initialize fields at their declaration when possible</h3><a class="heading-link" href="#do-initialize-fields-at-their-declaration-when-possible" aria-label="Link to 'DO initialize fields at their declaration when possible' section">#</a></div>If a field doesn't depend on any constructor parameters, it can and should be initialized at its declaration. It takes less code and avoids duplication when the class has multiple constructors. <?code-excerpt "usage_bad.dart (field-init-at-decl)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class ProfileMark { final String name; final DateTime start; ProfileMark(this.name) : start = DateTime.now(); ProfileMark.unnamed() : name = '', start = DateTime.now(); }</code></pre></div></div><?code-excerpt "usage_good.dart (field-init-at-decl)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class ProfileMark { final String name; final DateTime start = DateTime.now(); ProfileMark(this.name); ProfileMark.unnamed() : name = ''; }</code></pre></div></div>Some fields can't be initialized at their declarations because they need to reference <code>this</code>—to use other fields or call methods, for example. However, if the field is marked <code>late</code>, then the initializer can access <code>this</code>.Of course, if a field depends on constructor parameters, or is initialized differently by different constructors, then this guideline does not apply.<div class="header-wrapper"><h2 id="constructors">Constructors</h2><a class="heading-link" href="#constructors" aria-label="Link to 'Constructors' section">#</a></div>The following best practices apply to declaring constructors for a class.<div class="header-wrapper"><h3 id="do-use-initializing-formals-when-possible">DO use initializing formals when possible</h3><a class="heading-link" href="#do-use-initializing-formals-when-possible" aria-label="Link to 'DO use initializing formals when possible' section">#</a></div>Linter rule: <a href="/tools/linter-rules/prefer_initializing_formals">prefer_initializing_formals</a>Many fields are initialized directly from a constructor parameter, like: <?code-excerpt "usage_bad.dart (field-init-as-param)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Point { double x, y; Point(double x, double y) : x = x, y = y; }</code></pre></div></div>We've got to type <code>x</code> four times here to define a field. We can do better: <?code-excerpt "usage_good.dart (field-init-as-param)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Point { double x, y; Point(this.x, this.y); }</code></pre></div></div>This <code>this.</code> syntax before a constructor parameter is called an "initializing formal". You can't always take advantage of it. Sometimes you want to have a named parameter whose name doesn't match the name of the field you are initializing. But when you can use initializing formals, you should.<div class="header-wrapper"><h3 id="dont-use-late-when-a-constructor-initializer-list-will-do">DON'T use <code>late</code> when a constructor initializer list will do</h3><a class="heading-link" href="#dont-use-late-when-a-constructor-initializer-list-will-do" aria-label="Link to 'DON'T use late when a constructor initializer list will do' section">#</a></div>Dart requires you to initialize non-nullable fields before they can be read. Since fields can be read inside the constructor body, this means you get an error if you don't initialize a non-nullable field before the body runs.You can make this error go away by marking the field <code>late</code>. That turns the compile-time error into a runtime error if you access the field before it is initialized. That's what you need in some cases, but often the right fix is to initialize the field in the constructor initializer list: <?code-excerpt "usage_good.dart (late-init-list)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Point { double x, y; Point.polar(double theta, double radius) : x = cos(theta) * radius, y = sin(theta) * radius; }</code></pre></div></div><?code-excerpt "usage_bad.dart (late-init-list)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Point { late double x, y; Point.polar(double theta, double radius) { x = cos(theta) * radius; y = sin(theta) * radius; } }</code></pre></div></div>The initializer list gives you access to constructor parameters and lets you initialize fields before they can be read. So, if it's possible to use an initializer list, that's better than making the field <code>late</code> and losing some static safety and performance.<div class="header-wrapper"><h3 id="do-use-instead-of-for-empty-constructor-bodies">DO use <code>;</code> instead of <code>{}</code> for empty constructor bodies</h3><a class="heading-link" href="#do-use-instead-of-for-empty-constructor-bodies" aria-label="Link to 'DO use ; instead of {} for empty constructor bodies' section">#</a></div>Linter rule: <a href="/tools/linter-rules/empty_constructor_bodies">empty_constructor_bodies</a>In Dart, a constructor with an empty body can be terminated with just a semicolon. (In fact, it's required for const constructors.) <?code-excerpt "usage_good.dart (semicolon-for-empty-body)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>class Point { double x, y; Point(this.x, this.y); }</code></pre></div></div><?code-excerpt "usage_bad.dart (semicolon-for-empty-body)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>class Point { double x, y; Point(this.x, this.y) {} }</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-new">DON'T use <code>new</code></h3><a class="heading-link" href="#dont-use-new" aria-label="Link to 'DON'T use new' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_new">unnecessary_new</a>The <code>new</code> keyword is optional when calling a constructor. Its meaning is not clear because factory constructors mean a <code>new</code> invocation may not actually return a new object.The language still permits <code>new</code>, but consider it deprecated and avoid using it in your code. <?code-excerpt "usage_good.dart (no-new)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Widget build(BuildContext context) { return Row( children: [RaisedButton(child: Text('Increment')), Text('Click!')], ); }</code></pre></div></div><?code-excerpt "usage_bad.dart (no-new)" replace="/new/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Widget build(BuildContext context) { return new Row( children: [ new RaisedButton(child: new Text('Increment')), new Text('Click!'), ], ); }</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-const-redundantly">DON'T use <code>const</code> redundantly</h3><a class="heading-link" href="#dont-use-const-redundantly" aria-label="Link to 'DON'T use const redundantly' section">#</a></div>Linter rule: <a href="/tools/linter-rules/unnecessary_const">unnecessary_const</a>In contexts where an expression must be constant, the <code>const</code> keyword is implicit, doesn't need to be written, and shouldn't. Those contexts are any expression inside:<ul><li>A const collection literal.</li><li>A const constructor call</li><li>A metadata annotation.</li><li>The initializer for a const variable declaration.</li><li>A switch case expression—the part right after <code>case</code> before the <code>:</code>, not the body of the case.</li></ul>(Default values are not included in this list because future versions of Dart may support non-const default values.)Basically, any place where it would be an error to write <code>new</code> instead of <code>const</code>, Dart allows you to omit the <code>const</code>. <?code-excerpt "usage_good.dart (no-const)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>const primaryColors = [ Color('red', [255, 0, 0]), Color('green', [0, 255, 0]), Color('blue', [0, 0, 255]), ];</code></pre></div></div><?code-excerpt "usage_bad.dart (no-const)" replace="/ (const)/ [!$1!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>const primaryColors = const [ const Color('red', const [255, 0, 0]), const Color('green', const [0, 255, 0]), const Color('blue', const [0, 0, 255]), ];</code></pre></div></div><div class="header-wrapper"><h2 id="error-handling">Error handling</h2><a class="heading-link" href="#error-handling" aria-label="Link to 'Error handling' section">#</a></div>Dart uses exceptions when an error occurs in your program. The following best practices apply to catching and throwing exceptions.<div class="header-wrapper"><h3 id="avoid-catches-without-on-clauses">AVOID catches without <code>on</code> clauses</h3><a class="heading-link" href="#avoid-catches-without-on-clauses" aria-label="Link to 'AVOID catches without on clauses' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_catches_without_on_clauses">avoid_catches_without_on_clauses</a>A catch clause with no <code>on</code> qualifier catches anything thrown by the code in the try block. <a href="https://blog.codinghorror.com/new-programming-jargon/">Pokémon exception handling</a> is very likely not what you want. Does your code correctly handle <a href="https://api.dart.dev/dart-core/StackOverflowError-class.html">StackOverflowError</a> or <a href="https://api.dart.dev/dart-core/OutOfMemoryError-class.html">OutOfMemoryError</a>? If you incorrectly pass the wrong argument to a method in that try block do you want to have your debugger point you to the mistake or would you rather that helpful <a href="https://api.dart.dev/dart-core/ArgumentError-class.html">ArgumentError</a> get swallowed? Do you want any <code>assert()</code> statements inside that code to effectively vanish since you're catching the thrown <a href="https://api.dart.dev/dart-core/AssertionError-class.html">AssertionError</a>s?The answer is probably "no", in which case you should filter the types you catch. In most cases, you should have an <code>on</code> clause that limits you to the kinds of runtime failures you are aware of and are correctly handling.In rare cases, you may wish to catch any runtime error. This is usually in framework or low-level code that tries to insulate arbitrary application code from causing problems. Even here, it is usually better to catch <a href="https://api.dart.dev/dart-core/Exception-class.html">Exception</a> than to catch all types. Exception is the base class for all runtime errors and excludes errors that indicate programmatic bugs in the code.<div class="header-wrapper"><h3 id="dont-discard-errors-from-catches-without-on-clauses">DON'T discard errors from catches without <code>on</code> clauses</h3><a class="heading-link" href="#dont-discard-errors-from-catches-without-on-clauses" aria-label="Link to 'DON'T discard errors from catches without on clauses' section">#</a></div>If you really do feel you need to catch everything that can be thrown from a region of code, do something with what you catch. Log it, display it to the user or rethrow it, but do not silently discard it.<div class="header-wrapper"><h3 id="do-throw-objects-that-implement-error-only-for-programmatic-errors">DO throw objects that implement <code>Error</code> only for programmatic errors</h3><a class="heading-link" href="#do-throw-objects-that-implement-error-only-for-programmatic-errors" aria-label="Link to 'DO throw objects that implement Error only for programmatic errors' section">#</a></div>The <a href="https://api.dart.dev/dart-core/Error-class.html">Error</a> class is the base class for programmatic errors. When an object of that type or one of its subinterfaces like <a href="https://api.dart.dev/dart-core/ArgumentError-class.html">ArgumentError</a> is thrown, it means there is a bug in your code. When your API wants to report to a caller that it is being used incorrectly throwing an Error sends that signal clearly.Conversely, if the exception is some kind of runtime failure that doesn't indicate a bug in the code, then throwing an Error is misleading. Instead, throw one of the core Exception classes or some other type.<div class="header-wrapper"><h3 id="dont-explicitly-catch-error-or-types-that-implement-it">DON'T explicitly catch <code>Error</code> or types that implement it</h3><a class="heading-link" href="#dont-explicitly-catch-error-or-types-that-implement-it" aria-label="Link to 'DON'T explicitly catch Error or types that implement it' section">#</a></div>Linter rule: <a href="/tools/linter-rules/avoid_catching_errors">avoid_catching_errors</a>This follows from the above. Since an Error indicates a bug in your code, it should unwind the entire callstack, halt the program, and print a stack trace so you can locate and fix the bug.Catching errors of these types breaks that process and masks the bug. Instead of adding error-handling code to deal with this exception after the fact, go back and fix the code that is causing it to be thrown in the first place.<div class="header-wrapper"><h3 id="do-use-rethrow-to-rethrow-a-caught-exception">DO use <code>rethrow</code> to rethrow a caught exception</h3><a class="heading-link" href="#do-use-rethrow-to-rethrow-a-caught-exception" aria-label="Link to 'DO use rethrow to rethrow a caught exception' section">#</a></div>Linter rule: <a href="/tools/linter-rules/use_rethrow_when_possible">use_rethrow_when_possible</a>If you decide to rethrow an exception, prefer using the <code>rethrow</code> statement instead of throwing the same exception object using <code>throw</code>. <code>rethrow</code> preserves the original stack trace of the exception. <code>throw</code> on the other hand resets the stack trace to the last thrown position. <?code-excerpt "usage_bad.dart (rethrow)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>try { somethingRisky(); } catch (e) { if (!canHandle(e)) throw e; handle(e); }</code></pre></div></div><?code-excerpt "usage_good.dart (rethrow)" replace="/rethrow/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>try { somethingRisky(); } catch (e) { if (!canHandle(e)) rethrow; handle(e); }</code></pre></div></div><div class="header-wrapper"><h2 id="asynchrony">Asynchrony</h2><a class="heading-link" href="#asynchrony" aria-label="Link to 'Asynchrony' section">#</a></div>Dart has several language features to support asynchronous programming. The following best practices apply to asynchronous coding.<div class="header-wrapper"><h3 id="prefer-asyncawait-over-using-raw-futures">PREFER async/await over using raw futures</h3><a class="heading-link" href="#prefer-asyncawait-over-using-raw-futures" aria-label="Link to 'PREFER async/await over using raw futures' section">#</a></div>Asynchronous code is notoriously hard to read and debug, even when using a nice abstraction like futures. The <code>async</code>/<code>await</code> syntax improves readability and lets you use all of the Dart control flow structures within your async code. <?code-excerpt "usage_good.dart (async-await)" replace="/async|await/[!$&!]/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<int> countActivePlayers(String teamName) async { try { var team = await downloadTeam(teamName); if (team == null) return 0; var players = await team.roster; return players.where((player) => player.isActive).length; } catch (e) { log.error(e); return 0; } }</code></pre></div></div><?code-excerpt "usage_bad.dart (async-await)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Future<int> countActivePlayers(String teamName) { return downloadTeam(teamName) .then((team) { if (team == null) return Future.value(0); return team.roster.then((players) { return players.where((player) => player.isActive).length; }); }) .catchError((e) { log.error(e); return 0; }); }</code></pre></div></div><div class="header-wrapper"><h3 id="dont-use-async-when-it-has-no-useful-effect">DON'T use <code>async</code> when it has no useful effect</h3><a class="heading-link" href="#dont-use-async-when-it-has-no-useful-effect" aria-label="Link to 'DON'T use async when it has no useful effect' section">#</a></div>It's easy to get in the habit of using <code>async</code> on any function that does anything related to asynchrony. But in some cases, it's extraneous. If you can omit the <code>async</code> without changing the behavior of the function, do so. <?code-excerpt "usage_good.dart (unnecessary-async)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<int> fastestBranch(Future<int> left, Future<int> right) { return Future.any([left, right]); }</code></pre></div></div><?code-excerpt "usage_bad.dart (unnecessary-async)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Future<int> fastestBranch(Future<int> left, Future<int> right) async { return Future.any([left, right]); }</code></pre></div></div>Cases where <code>async</code> is useful include:<ul><li>You are using <code>await</code>. (This is the obvious one.)</li><li>You are returning an error asynchronously. <code>async</code> and then <code>throw</code> is shorter than <code>return Future.error(...)</code>.</li><li>You are returning a value and you want it implicitly wrapped in a future. <code>async</code> is shorter than <code>Future.value(...)</code>.</li></ul> <?code-excerpt "usage_good.dart (async)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<void> usesAwait(Future<String> later) async { print(await later); } Future<void> asyncError() async { throw 'Error!'; } Future<String> asyncValue() async => 'value';</code></pre></div></div><div class="header-wrapper"><h3 id="consider-using-higher-order-methods-to-transform-a-stream">CONSIDER using higher-order methods to transform a stream</h3><a class="heading-link" href="#consider-using-higher-order-methods-to-transform-a-stream" aria-label="Link to 'CONSIDER using higher-order methods to transform a stream' section">#</a></div>This parallels the above suggestion on iterables. Streams support many of the same methods and also handle things like transmitting errors, closing, etc. correctly.<div class="header-wrapper"><h3 id="avoid-using-completer-directly">AVOID using Completer directly</h3><a class="heading-link" href="#avoid-using-completer-directly" aria-label="Link to 'AVOID using Completer directly' section">#</a></div>Many people new to asynchronous programming want to write code that produces a future. The constructors in Future don't seem to fit their need so they eventually find the Completer class and use that. <?code-excerpt "usage_bad.dart (avoid-completer)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Future<bool> fileContainsBear(String path) { var completer = Completer<bool>(); File(path).readAsString().then((contents) { completer.complete(contents.contains('bear')); }); return completer.future; }</code></pre></div></div>Completer is needed for two kinds of low-level code: new asynchronous primitives, and interfacing with asynchronous code that doesn't use futures. Most other code should use async/await or <a href="https://api.dart.dev/dart-async/Future/then.html"><code>Future.then()</code></a>, because they're clearer and make error handling easier. <?code-excerpt "usage_good.dart (avoid-completer)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<bool> fileContainsBear(String path) { return File(path).readAsString().then((contents) { return contents.contains('bear'); }); }</code></pre></div></div><?code-excerpt "usage_good.dart (avoid-completer-alt)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<bool> fileContainsBear(String path) async { var contents = await File(path).readAsString(); return contents.contains('bear'); }</code></pre></div></div><div class="header-wrapper"><h3 id="do-test-for-futuret-when-disambiguating-a-futureort-whose-type-argument-could-be-object">DO test for <code>Future<T></code> when disambiguating a <code>FutureOr<T></code> whose type argument could be <code>Object</code></h3><a class="heading-link" href="#do-test-for-futuret-when-disambiguating-a-futureort-whose-type-argument-could-be-object" aria-label="Link to 'DO test for Future<T> when disambiguating a FutureOr<T> whose type argument could be Object' section">#</a></div>Before you can do anything useful with a <code>FutureOr<T></code>, you typically need to do an <code>is</code> check to see if you have a <code>Future<T></code> or a bare <code>T</code>. If the type argument is some specific type as in <code>FutureOr<int></code>, it doesn't matter which test you use, <code>is int</code> or <code>is Future<int></code>. Either works because those two types are disjoint.However, if the value type is <code>Object</code> or a type parameter that could possibly be instantiated with <code>Object</code>, then the two branches overlap. <code>Future<Object></code> itself implements <code>Object</code>, so <code>is Object</code> or <code>is T</code> where <code>T</code> is some type parameter that could be instantiated with <code>Object</code> returns true even when the object is a future. Instead, explicitly test for the <code>Future</code> case: <?code-excerpt "usage_good.dart (test-future-or)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good">gooddart<pre class="shiki dash-light" tabindex="0"><code>Future<T> logValue<T>(FutureOr<T> value) async { if (value is Future<T>) { var result = await value; print(result); return result; } else { print(value); return value; } }</code></pre></div></div><?code-excerpt "usage_bad.dart (test-future-or)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad">baddart<pre class="shiki dash-light" tabindex="0"><code>Future<T> logValue<T>(FutureOr<T> value) async { if (value is T) { print(value); return value; } else { var result = await value; print(result); return result; } }</code></pre></div></div>In the bad example, if you pass it a <code>Future<Object></code>, it incorrectly treats it like a bare, synchronous value.<nav id="prev-next"><ul><li class="previous"><a href="/effective-dart/documentation">&lang;  Documentation</a></li><li class="next"><a href="/effective-dart/design">Design  &rang;</a></li></ul></nav>Unless stated otherwise, the documentation on this site reflects Dart 3.7.2. Page last updated on 2025-02-12. <a href="https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/usage.md" target="_blank" rel="noopener">View source</a> or <a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/effective-dart/usage/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/usage.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</div></article></main></div><footer id="page-footer"><div class="footer-section footer-main"><a href="/" class="brand" title="Dart"><img src="/assets/img/logo/logo-white-text.svg" alt="Dart" width="164"></a><div class="footer-social-links"><a href="https://medium.com/dartlang" target="_blank" rel="noopener" title="Dart's Medium publication"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="Dart's GitHub organization"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://bsky.app/profile/dart.dev" target="_blank" rel="noopener" title="Dart's Bluesky profile"><svg><use href="/assets/img/social/bluesky.svg#bluesky"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="Dart's X (Twitter) profile"><svg><use href="/assets/img/social/x.svg#x"></use></svg></a></div></div><div class="footer-section footer-tray"><div class="footer-licenses">Except as otherwise noted, this site is licensed under a <a href="https://creativecommons.org/licenses/by/4.0/">Creative Commons Attribution 4.0 International License</a>, and code samples are licensed under the <a href="https://opensource.org/licenses/BSD-3-Clause">3-Clause BSD License</a>.</div><div class="footer-utility-links"><ul><li><a href="/terms" title="Terms of use">Terms</a></li><li><a href="https://policies.google.com/privacy" target="_blank" rel="noopener" title="Privacy policy">Privacy</a></li><li><a href="/security" title="Security philosophy and practices">Security</a></li></ul></div></div></footer></div></body></html>