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="Best practices for building consistent, maintainable, and efficient Dart libraries."><title>Effective Dart | 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"><meta name="twitter:description" content="Best practices for building consistent, maintainable, and efficient Dart libraries."><meta property="og:title" content="Effective Dart"><meta property="og:description" content="Best practices for building consistent, maintainable, and efficient Dart libraries."><meta property="og:url" content="/effective-dart/"><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"><p>dart.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic.</p><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"><p>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>.</p></div><header id="site-header"><nav id="mainnav"><div id="menu-toggle"><span class="material-symbols" title="Toggle side navigation menu." aria-label="Toggle side navigation menu." type="button">menu</span></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"><span>Docs</span></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"><span>Language</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1"><li class="nav-item"><a class="nav-link" href="/language"><div><span>Introduction</span></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"><span>Syntax basics</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables"><div><span>Variables</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/operators"><div><span>Operators</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/comments"><div><span>Comments</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/metadata"><div><span>Metadata</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/libraries"><div><span>Libraries & imports</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/keywords"><div><span>Keywords</span></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"><span>Types</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types"><div><span>Built-in types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/records"><div><span>Records</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/collections"><div><span>Collections</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/generics"><div><span>Generics</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs"><div><span>Typedefs</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/type-system"><div><span>Type system</span></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"><span>Patterns</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns"><div><span>Overview & usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types"><div><span>Pattern types</span></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><span>Applied tutorial</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions"><div><span>Functions</span></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"><span>Control flow</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops"><div><span>Loops</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/branches"><div><span>Branches</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling"><div><span>Error handling</span></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"><span>Classes & objects</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes"><div><span>Classes</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/constructors"><div><span>Constructors</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/methods"><div><span>Methods</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extend"><div><span>Extend a class</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/mixins"><div><span>Mixins</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/enums"><div><span>Enums</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods"><div><span>Extension methods</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types"><div><span>Extension types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects"><div><span>Callable objects</span></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"><span>Class modifiers</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers"><div><span>Overview & usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis"><div><span>Class modifiers for API maintainers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference"><div><span>Reference</span></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"><span>Concurrency</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/async"><div><span>Asynchronous support</span></div></a></li><li class="nav-item"><a class="nav-link" href="/language/isolates"><div><span>Isolates</span></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"><span>Null safety</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety"><div><span>Sound null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide"><div><span>Migrating to null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety"><div><span>Understanding null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety"><div><span>Unsound null safety</span></div></a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq"><div><span>FAQ</span></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"><span>Core libraries</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core"><div><span>dart:core</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async"><div><span>dart:async</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math"><div><span>dart:math</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert"><div><span>dart:convert</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io"><div><span>dart:io</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div><span>dart:js_interop</span></div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables"><div><span>Iterable collections</span></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"><span>Asynchronous programming</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await"><div><span>Tutorial</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling"><div><span>Futures and error handling</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams"><div><span>Using streams</span></div></a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams"><div><span>Creating streams</span></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"><span>Effective Dart</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-3"><li class="nav-item"><a class="nav-link active" href="/effective-dart"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style"><div><span>Style</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/documentation"><div><span>Documentation</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage"><div><span>Usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design"><div><span>Design</span></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"><span>Packages</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages"><div><span>How to use packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages"><div><span>Commonly used packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/create-packages"><div><span>Creating packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing"><div><span>Publishing packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages"><div><span>Writing package pages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/workspaces"><div><span>Workspaces (monorepo support)</span></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"><span>Package reference</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-4-7"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies"><div><span>Dependencies</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary"><div><span>Glossary</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout"><div><span>Package layout conventions</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables"><div><span>Pub environment variables</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec"><div><span>Pubspec file</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot"><div><span>Troubleshooting pub</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers"><div><span>Verified publishers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories"><div><span>Security advisories</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning"><div><span>Versioning</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories"><div><span>Custom package repositories</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/tools/pub/private-files"><div><span>What not to commit</span></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"><span>Development</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5"><li class="nav-item"><a class="nav-link" href="/libraries/serialization/json"><div><span>JSON serialization</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/number-representation"><div><span>Number representation</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis"><div><span>Google APIs</span></div></a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps"><div><span>Multi-platform apps</span></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"><span>Command-line & server apps</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started"><div><span>Get started</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline"><div><span>Write command-line apps</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data"><div><span>Fetch data from the internet</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver"><div><span>Write HTTP servers</span></div></a></li><li class="nav-item"><a class="nav-link" href="/server/libraries"><div><span>Libraries & packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud"><div><span>Google Cloud</span></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"><span>Web apps</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/get-started"><div><span>Get started</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/deployment"><div><span>Deployment</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/libraries"><div><span>Libraries & packages</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/wasm"><div><span>Wasm compilation</span></div></a></li></ul></li><li class="nav-item"><a class="nav-link" href="/libraries/core/environment-declarations"><div><span>Environment declarations</span></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"><span>Interoperability</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop"><div><span>C interop</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop"><div><span>Objective-C & Swift interop</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop"><div><span>Java & Kotlin interop</span></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"><span>JavaScript interop</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage"><div><span>Usage</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types"><div><span>JS types</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials"><div><span>Tutorials</span></div></a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop"><div><span>Past JS interop</span></div></a></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web"><div><span>Web interop</span></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"><span>Tools & techniques</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools"><div><span>Overview</span></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"><span>Editors & debuggers</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin"><div><span>IntelliJ & Android Studio</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code"><div><span>VS Code</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools"><div><span>Dart DevTools</span></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"><span>DartPad</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot"><div><span>Troubleshooting DartPad</span></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"><span>Command-line tools</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></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"><span>Dart SDK</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk"><div><span>Overview</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool"><div><span>dart</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze"><div><span>dart analyze</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile"><div><span>dart compile</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create"><div><span>dart create</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc"><div><span>dart doc</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix"><div><span>dart fix</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format"><div><span>dart format</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info"><div><span>dart info</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd"><div><span>dart pub</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run"><div><span>dart run</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test"><div><span>dart test</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime"><div><span>dartaotruntime</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags"><div><span>Experiment flags</span></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"><span>Other command-line tools</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse show" id="-sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner"><div><span>build_runner</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev"><div><span>webdev</span></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"><span>Static analysis</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis"><div><span>Customizing static analysis</span></div></a></li><li class="nav-item"><a class="nav-link" href="/deprecated/sound-problems"><div><span>Fixing common type problems</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons"><div><span>Fixing type promotion failures</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules"><div><span>Linter rules</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages"><div><span>Diagnostic messages</span></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"><span>Testing & optimization</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/tools/testing"><div><span>Testing</span></div></a></li><li class="nav-item"><a class="nav-link" href="/web/debugging"><div><span>Debugging web apps</span></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"><span>Resources</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></button><ul class="nav collapse" id="-sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet"><div><span>Language cheatsheet</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes"><div><span>Breaking changes</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/evolution"><div><span>Language evolution</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/language/spec"><div><span>Language specification</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration"><div><span>Dart 3 migration guide</span></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"><span>Coming from ...</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></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><span>JavaScript to Dart</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart"><div><span>Swift to Dart</span></div></a></li></ul></li><div class="sidenav-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq"><div><span>FAQ</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary"><div><span>Glossary</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/books"><div><span>Books</span></div></a></li><li class="nav-item"><a class="nav-link" href="/resources/videos"><div><span>Videos</span></div></a></li><li class="nav-item"><a class="nav-link" href="/tutorials"><div><span>Tutorials</span></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"><span>Related sites</span> <span class="material-symbols expander" aria-hidden="true">expand_more</span></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><span>API reference</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener"><div><span>Blog</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener"><div><span>DartPad (online editor)</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener"><div><span>Flutter</span><span class="material-symbols" aria-hidden="true">open_in_new</span></div></a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener"><div><span>Package site</span><span class="material-symbols" aria-hidden="true">open_in_new</span></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="#the-guides">The guides</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#how-to-read-the-guides">How to read the guides</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#glossary">Glossary</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#summary-of-all-rules">Summary of all rules</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#style">Style</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#documentation">Documentation</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#usage">Usage</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#design">Design</a></li></ul></li></ul></div><article><div class="content"><div id="site-content-title"><h1>Effective Dart</h1></div><div id="site-toc--inline" class="site-toc"><header class="site-toc__title">Contents</header><ul class="section-nav"><li class="toc-entry"><a href="#the-guides">The guides</a></li><li class="toc-entry"><a href="#how-to-read-the-guides">How to read the guides</a></li><li class="toc-entry"><a href="#glossary">Glossary</a></li><li class="toc-entry"><a href="#summary-of-all-rules">Summary of all rules</a><ul><li class="toc-entry"><a href="#style">Style</a></li><li class="toc-entry"><a href="#documentation">Documentation</a></li><li class="toc-entry"><a href="#usage">Usage</a></li><li class="toc-entry"><a href="#design">Design</a></li></ul></li></ul></div><p>Over the past several years, we've written a ton of Dart code and learned a lot about what works well and what doesn't. We're sharing this with you so you can write consistent, robust, fast code too. There are two overarching themes:</p><ol><li><p><strong>Be consistent.</strong> When it comes to things like formatting, and casing, arguments about which is better are subjective and impossible to resolve. What we do know is that being <em>consistent</em> is objectively helpful.</p><p>If two pieces of code look different it should be because they <em>are</em> different in some meaningful way. When a bit of code stands out and catches your eye, it should do so for a useful reason.</p></li><li><p><strong>Be brief.</strong> Dart was designed to be familiar, so it inherits many of the same statements and expressions as C, Java, JavaScript and other languages. But we created Dart because there is a lot of room to improve on what those languages offer. We added a bunch of features, from string interpolation to initializing formals, to help you express your intent more simply and easily.</p><p>If there are multiple ways to say something, you should generally pick the most concise one. This is not to say you should <a href="https://en.wikipedia.org/wiki/Code_golf">code golf</a> yourself into cramming a whole program into a single line. The goal is code that is <em>economical</em>, not <em>dense</em>.</p></li></ol><div class="header-wrapper"><h2 id="the-guides">The guides</h2><a class="heading-link" href="#the-guides" aria-label="Link to 'The guides' section">#</a></div><p>We split the guidelines into a few separate pages for easy digestion:</p><ul><li><p><strong><a href="/effective-dart/style">Style Guide</a></strong> – This defines the rules for laying out and organizing code, or at least the parts that <a href="/tools/dart-format"><code>dart format</code></a> doesn't handle for you. The style guide also specifies how identifiers are formatted: <code>camelCase</code>, <code>using_underscores</code>, etc.</p></li><li><p><strong><a href="/effective-dart/documentation">Documentation Guide</a></strong> – This tells you everything you need to know about what goes inside comments. Both doc comments and regular, run-of-the-mill code comments.</p></li><li><p><strong><a href="/effective-dart/usage">Usage Guide</a></strong> – This teaches you how to make the best use of language features to implement behavior. If it's in a statement or expression, it's covered here.</p></li><li><p><strong><a href="/effective-dart/design">Design Guide</a></strong> – This is the softest guide, but the one with the widest scope. It covers what we've learned about designing consistent, usable APIs for libraries. If it's in a type signature or declaration, this goes over it.</p></li></ul><p>For links to all the guidelines, see the <a href="#summary-of-all-rules">summary</a>.</p><div class="header-wrapper"><h2 id="how-to-read-the-guides">How to read the guides</h2><a class="heading-link" href="#how-to-read-the-guides" aria-label="Link to 'How to read the guides' section">#</a></div><p>Each guide is broken into a few sections. Sections contain a list of guidelines. Each guideline starts with one of these words:</p><ul><li><p><strong>DO</strong> guidelines describe practices that should always be followed. There will almost never be a valid reason to stray from them.</p></li><li><p><strong>DON'T</strong> guidelines are the converse: things that are almost never a good idea. Hopefully, we don't have as many of these as other languages do because we have less historical baggage.</p></li><li><p><strong>PREFER</strong> guidelines are practices that you <em>should</em> follow. However, there may be circumstances where it makes sense to do otherwise. Just make sure you understand the full implications of ignoring the guideline when you do.</p></li><li><p><strong>AVOID</strong> guidelines are the dual to "prefer": stuff you shouldn't do but where there may be good reasons to on rare occasions.</p></li><li><p><strong>CONSIDER</strong> guidelines are practices that you might or might not want to follow, depending on circumstances, precedents, and your own preference.</p></li></ul><p>Some guidelines describe an <strong>exception</strong> where the rule does <em>not</em> apply. When listed, the exceptions may not be exhaustive—you might still need to use your judgement on other cases.</p><p>This sounds like the police are going to beat down your door if you don't have your laces tied correctly. Things aren't that bad. Most of the guidelines here are common sense and we're all reasonable people. The goal, as always, is nice, readable and maintainable code.</p><p>The Dart analyzer provides a linter to help you write good, consistent code that follows these and other guidelines. If one or more <a href="/tools/linter-rules">linter rules</a> exist that can help you follow a guideline then the guideline links to those rules. The links use the following format:</p><p class="linter-rule">Linter rule: <a href="/tools/linter-rules/unnecessary_getters_setters">unnecessary_getters_setters</a></p><p>To learn how to use the linter, see <a href="/tools/analysis#enabling-linter-rules">Enabling linter rules</a> and the list of <a href="/tools/linter-rules">linter rules</a>.</p><div class="header-wrapper"><h2 id="glossary">Glossary</h2><a class="heading-link" href="#glossary" aria-label="Link to 'Glossary' section">#</a></div><p>To keep the guidelines brief, we use a few shorthand terms to refer to different Dart constructs.</p><ul><li><p>A <strong>library member</strong> is a top-level field, getter, setter, or function. Basically, anything at the top level that isn't a type.</p></li><li><p>A <strong>class member</strong> is a constructor, field, getter, setter, function, or operator declared inside a class. Class members can be instance or static, abstract or concrete.</p></li><li><p>A <strong>member</strong> is either a library member or a class member.</p></li><li><p>A <strong>variable</strong>, when used generally, refers to top-level variables, parameters, and local variables. It doesn't include static or instance fields.</p></li><li><p>A <strong>type</strong> is any named type declaration: a class, typedef, or enum.</p></li><li><p>A <strong>property</strong> is a top-level variable, getter (inside a class or at the top level, instance or static), setter (same), or field (instance or static). Roughly any "field-like" named construct.</p></li></ul><div class="header-wrapper"><h2 id="summary-of-all-rules">Summary of all rules</h2><a class="heading-link" href="#summary-of-all-rules" aria-label="Link to 'Summary of all rules' section">#</a></div><div class="side-by-side"><div><div class="header-wrapper"><h3 id="style">Style</h3><a class="heading-link" href="#style" aria-label="Link to 'Style' section">#</a></div><p><strong>Identifiers</strong></p><ul><li><a href="/effective-dart/style#do-name-types-using-uppercamelcase">DO name types using <code>UpperCamelCase</code>.</a></li><li><a href="/effective-dart/style#do-name-extensions-using-uppercamelcase">DO name extensions using <code>UpperCamelCase</code>.</a></li><li><a href="/effective-dart/style#do-name-packages-and-file-system-entities-using-lowercase-with-underscores">DO name packages, directories, and source files using <code>lowercase_with_underscores</code>.</a></li><li><a href="/effective-dart/style#do-name-import-prefixes-using-lowercase_with_underscores">DO name import prefixes using <code>lowercase_with_underscores</code>.</a></li><li><a href="/effective-dart/style#do-name-other-identifiers-using-lowercamelcase">DO name other identifiers using <code>lowerCamelCase</code>.</a></li><li><a href="/effective-dart/style#prefer-using-lowercamelcase-for-constant-names">PREFER using <code>lowerCamelCase</code> for constant names.</a></li><li><a href="/effective-dart/style#do-capitalize-acronyms-and-abbreviations-longer-than-two-letters-like-words">DO capitalize acronyms and abbreviations longer than two letters like words.</a></li><li><a href="/effective-dart/style#prefer-using-_-__-etc-for-unused-callback-parameters">PREFER using <code>_</code>, <code>__</code>, etc. for unused callback parameters.</a></li><li><a href="/effective-dart/style#dont-use-a-leading-underscore-for-identifiers-that-arent-private">DON'T use a leading underscore for identifiers that aren't private.</a></li><li><a href="/effective-dart/style#dont-use-prefix-letters">DON'T use prefix letters.</a></li><li><a href="/effective-dart/style#dont-explicitly-name-libraries">DON'T explicitly name libraries.</a></li></ul><p><strong>Ordering</strong></p><ul><li><a href="/effective-dart/style#do-place-dart-imports-before-other-imports">DO place <code>dart:</code> imports before other imports.</a></li><li><a href="/effective-dart/style#do-place-package-imports-before-relative-imports">DO place <code>package:</code> imports before relative imports.</a></li><li><a href="/effective-dart/style#do-specify-exports-in-a-separate-section-after-all-imports">DO specify exports in a separate section after all imports.</a></li><li><a href="/effective-dart/style#do-sort-sections-alphabetically">DO sort sections alphabetically.</a></li></ul><p><strong>Formatting</strong></p><ul><li><a href="/effective-dart/style#do-format-your-code-using-dart-format">DO format your code using <code>dart format</code>.</a></li><li><a href="/effective-dart/style#consider-changing-your-code-to-make-it-more-formatter-friendly">CONSIDER changing your code to make it more formatter-friendly.</a></li><li><a href="/effective-dart/style#avoid-lines-longer-than-80-characters">AVOID lines longer than 80 characters.</a></li><li><a href="/effective-dart/style#do-use-curly-braces-for-all-flow-control-statements">DO use curly braces for all flow control statements.</a></li></ul></div><div><div class="header-wrapper"><h3 id="documentation">Documentation</h3><a class="heading-link" href="#documentation" aria-label="Link to 'Documentation' section">#</a></div><p><strong>Comments</strong></p><ul><li><a href="/effective-dart/documentation#do-format-comments-like-sentences">DO format comments like sentences.</a></li><li><a href="/effective-dart/documentation#dont-use-block-comments-for-documentation">DON'T use block comments for documentation.</a></li></ul><p><strong>Doc comments</strong></p><ul><li><a href="/effective-dart/documentation#do-use-doc-comments-to-document-members-and-types">DO use <code>///</code> doc comments to document members and types.</a></li><li><a href="/effective-dart/documentation#prefer-writing-doc-comments-for-public-apis">PREFER writing doc comments for public APIs.</a></li><li><a href="/effective-dart/documentation#consider-writing-a-library-level-doc-comment">CONSIDER writing a library-level doc comment.</a></li><li><a href="/effective-dart/documentation#consider-writing-doc-comments-for-private-apis">CONSIDER writing doc comments for private APIs.</a></li><li><a href="/effective-dart/documentation#do-start-doc-comments-with-a-single-sentence-summary">DO start doc comments with a single-sentence summary.</a></li><li><a href="/effective-dart/documentation#do-separate-the-first-sentence-of-a-doc-comment-into-its-own-paragraph">DO separate the first sentence of a doc comment into its own paragraph.</a></li><li><a href="/effective-dart/documentation#avoid-redundancy-with-the-surrounding-context">AVOID redundancy with the surrounding context.</a></li><li><a href="/effective-dart/documentation#prefer-starting-function-or-method-comments-with-third-person-verbs">PREFER starting function or method comments with third-person verbs.</a></li><li><a href="/effective-dart/documentation#prefer-starting-a-non-boolean-variable-or-property-comment-with-a-noun-phrase">PREFER starting a non-boolean variable or property comment with a noun phrase.</a></li><li><a href="/effective-dart/documentation#prefer-starting-a-boolean-variable-or-property-comment-with-whether-followed-by-a-noun-or-gerund-phrase">PREFER starting a boolean variable or property comment with "Whether" followed by a noun or gerund phrase.</a></li><li><a href="/effective-dart/documentation#dont-write-documentation-for-both-the-getter-and-setter-of-a-property">DON'T write documentation for both the getter and setter of a property.</a></li><li><a href="/effective-dart/documentation#prefer-starting-library-or-type-comments-with-noun-phrases">PREFER starting library or type comments with noun phrases.</a></li><li><a href="/effective-dart/documentation#consider-including-code-samples-in-doc-comments">CONSIDER including code samples in doc comments.</a></li><li><a href="/effective-dart/documentation#do-use-square-brackets-in-doc-comments-to-refer-to-in-scope-identifiers">DO use square brackets in doc comments to refer to in-scope identifiers.</a></li><li><a href="/effective-dart/documentation#do-use-prose-to-explain-parameters-return-values-and-exceptions">DO use prose to explain parameters, return values, and exceptions.</a></li><li><a href="/effective-dart/documentation#do-put-doc-comments-before-metadata-annotations">DO put doc comments before metadata annotations.</a></li></ul><p><strong>Markdown</strong></p><ul><li><a href="/effective-dart/documentation#avoid-using-markdown-excessively">AVOID using markdown excessively.</a></li><li><a href="/effective-dart/documentation#avoid-using-html-for-formatting">AVOID using HTML for formatting.</a></li><li><a href="/effective-dart/documentation#prefer-backtick-fences-for-code-blocks">PREFER backtick fences for code blocks.</a></li></ul><p><strong>Writing</strong></p><ul><li><a href="/effective-dart/documentation#prefer-brevity">PREFER brevity.</a></li><li><a href="/effective-dart/documentation#avoid-abbreviations-and-acronyms-unless-they-are-obvious">AVOID abbreviations and acronyms unless they are obvious.</a></li><li><a href="/effective-dart/documentation#prefer-using-this-instead-of-the-to-refer-to-a-members-instance">PREFER using "this" instead of "the" to refer to a member's instance.</a></li></ul></div><div><div class="header-wrapper"><h3 id="usage">Usage</h3><a class="heading-link" href="#usage" aria-label="Link to 'Usage' section">#</a></div><p><strong>Libraries</strong></p><ul><li><a href="/effective-dart/usage#do-use-strings-in-part-of-directives">DO use strings in <code>part of</code> directives.</a></li><li><a href="/effective-dart/usage#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.</a></li><li><a href="/effective-dart/usage#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>.</a></li><li><a href="/effective-dart/usage#prefer-relative-import-paths">PREFER relative import paths.</a></li></ul><p><strong>Null</strong></p><ul><li><a href="/effective-dart/usage#dont-explicitly-initialize-variables-to-null">DON'T explicitly initialize variables to <code>null</code>.</a></li><li><a href="/effective-dart/usage#dont-use-an-explicit-default-value-of-null">DON'T use an explicit default value of <code>null</code>.</a></li><li><a href="/effective-dart/usage#dont-use-true-or-false-in-equality-operations">DON'T use <code>true</code> or <code>false</code> in equality operations.</a></li><li><a href="/effective-dart/usage#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.</a></li><li><a href="/effective-dart/usage#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><p><strong>Strings</strong></p><ul><li><a href="/effective-dart/usage#do-use-adjacent-strings-to-concatenate-string-literals">DO use adjacent strings to concatenate string literals.</a></li><li><a href="/effective-dart/usage#prefer-using-interpolation-to-compose-strings-and-values">PREFER using interpolation to compose strings and values.</a></li><li><a href="/effective-dart/usage#avoid-using-curly-braces-in-interpolation-when-not-needed">AVOID using curly braces in interpolation when not needed.</a></li></ul><p><strong>Collections</strong></p><ul><li><a href="/effective-dart/usage#do-use-collection-literals-when-possible">DO use collection literals when possible.</a></li><li><a href="/effective-dart/usage#dont-use-length-to-see-if-a-collection-is-empty">DON'T use <code>.length</code> to see if a collection is empty.</a></li><li><a href="/effective-dart/usage#avoid-using-iterable-foreach-with-a-function-literal">AVOID using <code>Iterable.forEach()</code> with a function literal.</a></li><li><a href="/effective-dart/usage#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.</a></li><li><a href="/effective-dart/usage#do-use-wheretype-to-filter-a-collection-by-type">DO use <code>whereType()</code> to filter a collection by type.</a></li><li><a href="/effective-dart/usage#dont-use-cast-when-a-nearby-operation-will-do">DON'T use <code>cast()</code> when a nearby operation will do.</a></li><li><a href="/effective-dart/usage#avoid-using-cast">AVOID using <code>cast()</code>.</a></li></ul><p><strong>Functions</strong></p><ul><li><a href="/effective-dart/usage#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><a href="/effective-dart/usage#dont-create-a-lambda-when-a-tear-off-will-do">DON'T create a lambda when a tear-off will do.</a></li></ul><p><strong>Variables</strong></p><ul><li><a href="/effective-dart/usage#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.</a></li><li><a href="/effective-dart/usage#avoid-storing-what-you-can-calculate">AVOID storing what you can calculate.</a></li></ul><p><strong>Members</strong></p><ul><li><a href="/effective-dart/usage#dont-wrap-a-field-in-a-getter-and-setter-unnecessarily">DON'T wrap a field in a getter and setter unnecessarily.</a></li><li><a href="/effective-dart/usage#prefer-using-a-final-field-to-make-a-read-only-property">PREFER using a <code>final</code> field to make a read-only property.</a></li><li><a href="/effective-dart/usage#consider-using-for-simple-members">CONSIDER using <code>=></code> for simple members.</a></li><li><a href="/effective-dart/usage#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.</a></li><li><a href="/effective-dart/usage#do-initialize-fields-at-their-declaration-when-possible">DO initialize fields at their declaration when possible.</a></li></ul><p><strong>Constructors</strong></p><ul><li><a href="/effective-dart/usage#do-use-initializing-formals-when-possible">DO use initializing formals when possible.</a></li><li><a href="/effective-dart/usage#dont-use-late-when-a-constructor-initializer-list-will-do">DON'T use <code>late</code> when a constructor initializer list will do.</a></li><li><a href="/effective-dart/usage#do-use-instead-of-for-empty-constructor-bodies">DO use <code>;</code> instead of <code>{}</code> for empty constructor bodies.</a></li><li><a href="/effective-dart/usage#dont-use-new">DON'T use <code>new</code>.</a></li><li><a href="/effective-dart/usage#dont-use-const-redundantly">DON'T use <code>const</code> redundantly.</a></li></ul><p><strong>Error handling</strong></p><ul><li><a href="/effective-dart/usage#avoid-catches-without-on-clauses">AVOID catches without <code>on</code> clauses.</a></li><li><a href="/effective-dart/usage#dont-discard-errors-from-catches-without-on-clauses">DON'T discard errors from catches without <code>on</code> clauses.</a></li><li><a href="/effective-dart/usage#do-throw-objects-that-implement-error-only-for-programmatic-errors">DO throw objects that implement <code>Error</code> only for programmatic errors.</a></li><li><a href="/effective-dart/usage#dont-explicitly-catch-error-or-types-that-implement-it">DON'T explicitly catch <code>Error</code> or types that implement it.</a></li><li><a href="/effective-dart/usage#do-use-rethrow-to-rethrow-a-caught-exception">DO use <code>rethrow</code> to rethrow a caught exception.</a></li></ul><p><strong>Asynchrony</strong></p><ul><li><a href="/effective-dart/usage#prefer-asyncawait-over-using-raw-futures">PREFER async/await over using raw futures.</a></li><li><a href="/effective-dart/usage#dont-use-async-when-it-has-no-useful-effect">DON'T use <code>async</code> when it has no useful effect.</a></li><li><a href="/effective-dart/usage#consider-using-higher-order-methods-to-transform-a-stream">CONSIDER using higher-order methods to transform a stream.</a></li><li><a href="/effective-dart/usage#avoid-using-completer-directly">AVOID using Completer directly.</a></li><li><a href="/effective-dart/usage#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>.</a></li></ul></div><div><div class="header-wrapper"><h3 id="design">Design</h3><a class="heading-link" href="#design" aria-label="Link to 'Design' section">#</a></div><p><strong>Names</strong></p><ul><li><a href="/effective-dart/design#do-use-terms-consistently">DO use terms consistently.</a></li><li><a href="/effective-dart/design#avoid-abbreviations">AVOID abbreviations.</a></li><li><a href="/effective-dart/design#prefer-putting-the-most-descriptive-noun-last">PREFER putting the most descriptive noun last.</a></li><li><a href="/effective-dart/design#consider-making-the-code-read-like-a-sentence">CONSIDER making the code read like a sentence.</a></li><li><a href="/effective-dart/design#prefer-a-noun-phrase-for-a-non-boolean-property-or-variable">PREFER a noun phrase for a non-boolean property or variable.</a></li><li><a href="/effective-dart/design#prefer-a-non-imperative-verb-phrase-for-a-boolean-property-or-variable">PREFER a non-imperative verb phrase for a boolean property or variable.</a></li><li><a href="/effective-dart/design#consider-omitting-the-verb-for-a-named-boolean-parameter">CONSIDER omitting the verb for a named boolean <em>parameter</em>.</a></li><li><a href="/effective-dart/design#prefer-the-positive-name-for-a-boolean-property-or-variable">PREFER the "positive" name for a boolean property or variable.</a></li><li><a href="/effective-dart/design#prefer-an-imperative-verb-phrase-for-a-function-or-method-whose-main-purpose-is-a-side-effect">PREFER an imperative verb phrase for a function or method whose main purpose is a side effect.</a></li><li><a href="/effective-dart/design#prefer-a-noun-phrase-or-non-imperative-verb-phrase-for-a-function-or-method-if-returning-a-value-is-its-primary-purpose">PREFER a noun phrase or non-imperative verb phrase for a function or method if returning a value is its primary purpose.</a></li><li><a href="/effective-dart/design#consider-an-imperative-verb-phrase-for-a-function-or-method-if-you-want-to-draw-attention-to-the-work-it-performs">CONSIDER an imperative verb phrase for a function or method if you want to draw attention to the work it performs.</a></li><li><a href="/effective-dart/design#avoid-starting-a-method-name-with-get">AVOID starting a method name with <code>get</code>.</a></li><li><a href="/effective-dart/design#prefer-naming-a-method-to___-if-it-copies-the-objects-state-to-a-new-object">PREFER naming a method <code>to___()</code> if it copies the object's state to a new object.</a></li><li><a href="/effective-dart/design#prefer-naming-a-method-as___-if-it-returns-a-different-representation-backed-by-the-original-object">PREFER naming a method <code>as___()</code> if it returns a different representation backed by the original object.</a></li><li><a href="/effective-dart/design#avoid-describing-the-parameters-in-the-functions-or-methods-name">AVOID describing the parameters in the function's or method's name.</a></li><li><a href="/effective-dart/design#do-follow-existing-mnemonic-conventions-when-naming-type-parameters">DO follow existing mnemonic conventions when naming type parameters.</a></li></ul><p><strong>Libraries</strong></p><ul><li><a href="/effective-dart/design#prefer-making-declarations-private">PREFER making declarations private.</a></li><li><a href="/effective-dart/design#consider-declaring-multiple-classes-in-the-same-library">CONSIDER declaring multiple classes in the same library.</a></li></ul><p><strong>Classes and mixins</strong></p><ul><li><a href="/effective-dart/design#avoid-defining-a-one-member-abstract-class-when-a-simple-function-will-do">AVOID defining a one-member abstract class when a simple function will do.</a></li><li><a href="/effective-dart/design#avoid-defining-a-class-that-contains-only-static-members">AVOID defining a class that contains only static members.</a></li><li><a href="/effective-dart/design#avoid-extending-a-class-that-isnt-intended-to-be-subclassed">AVOID extending a class that isn't intended to be subclassed.</a></li><li><a href="/effective-dart/design#do-document-if-your-class-supports-being-extended">DO document if your class supports being extended.</a></li><li><a href="/effective-dart/design#avoid-implementing-a-class-that-isnt-intended-to-be-an-interface">AVOID implementing a class that isn't intended to be an interface.</a></li><li><a href="/effective-dart/design#do-document-if-your-class-supports-being-used-as-an-interface">DO document if your class supports being used as an interface.</a></li><li><a href="/effective-dart/design#prefer-defining-a-pure-mixin-or-pure-class-to-a-mixin-class">PREFER defining a pure <code>mixin</code> or pure <code>class</code> to a <code>mixin class</code>.</a></li></ul><p><strong>Constructors</strong></p><ul><li><a href="/effective-dart/design#consider-making-your-constructor-const-if-the-class-supports-it">CONSIDER making your constructor <code>const</code> if the class supports it.</a></li></ul><p><strong>Members</strong></p><ul><li><a href="/effective-dart/design#prefer-making-fields-and-top-level-variables-final">PREFER making fields and top-level variables <code>final</code>.</a></li><li><a href="/effective-dart/design#do-use-getters-for-operations-that-conceptually-access-properties">DO use getters for operations that conceptually access properties.</a></li><li><a href="/effective-dart/design#do-use-setters-for-operations-that-conceptually-change-properties">DO use setters for operations that conceptually change properties.</a></li><li><a href="/effective-dart/design#dont-define-a-setter-without-a-corresponding-getter">DON'T define a setter without a corresponding getter.</a></li><li><a href="/effective-dart/design#avoid-using-runtime-type-tests-to-fake-overloading">AVOID using runtime type tests to fake overloading.</a></li><li><a href="/effective-dart/design#avoid-public-late-final-fields-without-initializers">AVOID public <code>late final</code> fields without initializers.</a></li><li><a href="/effective-dart/design#avoid-returning-nullable-future-stream-and-collection-types">AVOID returning nullable <code>Future</code>, <code>Stream</code>, and collection types.</a></li><li><a href="/effective-dart/design#avoid-returning-this-from-methods-just-to-enable-a-fluent-interface">AVOID returning <code>this</code> from methods just to enable a fluent interface.</a></li></ul><p><strong>Types</strong></p><ul><li><a href="/effective-dart/design#do-type-annotate-variables-without-initializers">DO type annotate variables without initializers.</a></li><li><a href="/effective-dart/design#do-type-annotate-fields-and-top-level-variables-if-the-type-isnt-obvious">DO type annotate fields and top-level variables if the type isn't obvious.</a></li><li><a href="/effective-dart/design#dont-redundantly-type-annotate-initialized-local-variables">DON'T redundantly type annotate initialized local variables.</a></li><li><a href="/effective-dart/design#do-annotate-return-types-on-function-declarations">DO annotate return types on function declarations.</a></li><li><a href="/effective-dart/design#do-annotate-parameter-types-on-function-declarations">DO annotate parameter types on function declarations.</a></li><li><a href="/effective-dart/design#dont-annotate-inferred-parameter-types-on-function-expressions">DON'T annotate inferred parameter types on function expressions.</a></li><li><a href="/effective-dart/design#dont-type-annotate-initializing-formals">DON'T type annotate initializing formals.</a></li><li><a href="/effective-dart/design#do-write-type-arguments-on-generic-invocations-that-arent-inferred">DO write type arguments on generic invocations that aren't inferred.</a></li><li><a href="/effective-dart/design#dont-write-type-arguments-on-generic-invocations-that-are-inferred">DON'T write type arguments on generic invocations that are inferred.</a></li><li><a href="/effective-dart/design#avoid-writing-incomplete-generic-types">AVOID writing incomplete generic types.</a></li><li><a href="/effective-dart/design#do-annotate-with-dynamic-instead-of-letting-inference-fail">DO annotate with <code>dynamic</code> instead of letting inference fail.</a></li><li><a href="/effective-dart/design#prefer-signatures-in-function-type-annotations">PREFER signatures in function type annotations.</a></li><li><a href="/effective-dart/design#dont-specify-a-return-type-for-a-setter">DON'T specify a return type for a setter.</a></li><li><a href="/effective-dart/design#dont-use-the-legacy-typedef-syntax">DON'T use the legacy typedef syntax.</a></li><li><a href="/effective-dart/design#prefer-inline-function-types-over-typedefs">PREFER inline function types over typedefs.</a></li><li><a href="/effective-dart/design#prefer-using-function-type-syntax-for-parameters">PREFER using function type syntax for parameters.</a></li><li><a href="/effective-dart/design#avoid-using-dynamic-unless-you-want-to-disable-static-checking">AVOID using <code>dynamic</code> unless you want to disable static checking.</a></li><li><a href="/effective-dart/design#do-use-futurevoid-as-the-return-type-of-asynchronous-members-that-do-not-produce-values">DO use <code>Future<void></code> as the return type of asynchronous members that do not produce values.</a></li><li><a href="/effective-dart/design#avoid-using-futureort-as-a-return-type">AVOID using <code>FutureOr<T></code> as a return type.</a></li></ul><p><strong>Parameters</strong></p><ul><li><a href="/effective-dart/design#avoid-positional-boolean-parameters">AVOID positional boolean parameters.</a></li><li><a href="/effective-dart/design#avoid-optional-positional-parameters-if-the-user-may-want-to-omit-earlier-parameters">AVOID optional positional parameters if the user may want to omit earlier parameters.</a></li><li><a href="/effective-dart/design#avoid-mandatory-parameters-that-accept-a-special-no-argument-value">AVOID mandatory parameters that accept a special "no argument" value.</a></li><li><a href="/effective-dart/design#do-use-inclusive-start-and-exclusive-end-parameters-to-accept-a-range">DO use inclusive start and exclusive end parameters to accept a range.</a></li></ul><p><strong>Equality</strong></p><ul><li><a href="/effective-dart/design#do-override-hashcode-if-you-override">DO override <code>hashCode</code> if you override <code>==</code>.</a></li><li><a href="/effective-dart/design#do-make-your-operator-obey-the-mathematical-rules-of-equality">DO make your <code>==</code> operator obey the mathematical rules of equality.</a></li><li><a href="/effective-dart/design#avoid-defining-custom-equality-for-mutable-classes">AVOID defining custom equality for mutable classes.</a></li><li><a href="/effective-dart/design#dont-make-the-parameter-to-nullable">DON'T make the parameter to <code>==</code> nullable.</a></li></ul></div></div><nav id="prev-next"><ul><li class="previous"></li><li class="next"><a href="/effective-dart/style">Style  &rang;</a></li></ul></nav><p id="page-github-links"><span>Unless stated otherwise, the documentation on this site reflects Dart 3.7.0. Page last updated on 2024-05-06.</span> <a href="https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/index.md" target="_blank" rel="noopener">View source</a> <span>or </span><a href="https://github.com/dart-lang/site-www/issues/new?template=1_page_issue.yml&page-url=https://dart.dev/effective-dart/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/index.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</p></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>