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="Clear, helpful comments and documentation."><title>Effective Dart: Documentation | 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: Documentation"><meta name="twitter:description" content="Clear, helpful comments and documentation."><meta property="og:title" content="Effective Dart: Documentation"><meta property="og:description" content="Clear, helpful comments and documentation."><meta property="og:url" content="/effective-dart/documentation/"><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,0" rel="stylesheet"><link rel="stylesheet" href="/assets/css/main.css"><script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.7.0/jquery.min.js" integrity="sha512-3gJwYpMe3QewGELv8k/BX9vcqhryRdzRMxVfq6ngyWXwo03GFEzjsUm8Q7RZcHPHksttq7/GFoxjCVUjkjvPdw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/bootstrap/4.6.2/js/bootstrap.min.js" integrity="sha384-+sLIOodYLS7CIrQpBjl+C7nPvqq+FbNUBDunl/OZv93DB7Ln/533i8e/mZXLi/P+" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/js-cookie/3.0.5/js.cookie.min.js" integrity="sha512-nlp9/l96/EpjYBx7EP7pGASVXNe80hGhYAUrjeXnu/fyF5Py0/RXav4BBNs7n5Hx1WFhOEOWSAVjGeC3oKxDVQ==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="/assets/js/os-tabs.js"></script><script src="/assets/js/utilities.js"></script><script src="/assets/js/main.js"></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 show_banner"><a id="skip" href="#site-content-title">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. <a href="https://policies.google.com/technologies/cookies" target="_blank" rel="noopener">Learn more</a>.</p><button id="cookie-consent" class="btn btn-primary">OK, got it</button></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><header id="page-header" class="site-header"><nav id="mainnav" class="site-header"><div id="menu-toggle"><i class="material-symbols">menu</i></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="/guides" 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 class="banner"><p class="banner__text">Announcing Dart 3.5 and an updated Dart roadmap! <a href="https://medium.com/dartlang/dart-3-5-6ca36259fa2f" target="_blank">Learn more</a></p></div><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><div class="site-sidebar"><ul class="navbar-nav"><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="/guides" class="nav-link">Docs</a></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li></ul><ul class="nav flex-column"><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-1" role="button" aria-expanded="false" aria-controls="sidenav-1">Language</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1"><li class="nav-item"><a class="nav-link" href="/language">Introduction</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-2" href="#sidenav-1-2" role="button" aria-expanded="false" aria-controls="sidenav-1-2">Syntax basics</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-2"><li class="nav-item"><a class="nav-link" href="/language/variables">Variables</a></li><li class="nav-item"><a class="nav-link" href="/language/operators">Operators</a></li><li class="nav-item"><a class="nav-link" href="/language/comments">Comments</a></li><li class="nav-item"><a class="nav-link" href="/language/metadata">Metadata</a></li><li class="nav-item"><a class="nav-link" href="/language/libraries">Libraries & imports</a></li><li class="nav-item"><a class="nav-link" href="/language/keywords">Keywords</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-3" href="#sidenav-1-3" role="button" aria-expanded="false" aria-controls="sidenav-1-3">Types</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-3"><li class="nav-item"><a class="nav-link" href="/language/built-in-types">Built-in types</a></li><li class="nav-item"><a class="nav-link" href="/language/records">Records</a></li><li class="nav-item"><a class="nav-link" href="/language/collections">Collections</a></li><li class="nav-item"><a class="nav-link" href="/language/generics">Generics</a></li><li class="nav-item"><a class="nav-link" href="/language/typedefs">Typedefs</a></li><li class="nav-item"><a class="nav-link" href="/language/type-system">Type system</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-4" href="#sidenav-1-4" role="button" aria-expanded="false" aria-controls="sidenav-1-4">Patterns</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-4"><li class="nav-item"><a class="nav-link" href="/language/patterns">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/pattern-types">Pattern types</a></li><li class="nav-item"><a class="nav-link" href="https://codelabs.developers.google.com/codelabs/dart-patterns-records" target="_blank" rel="noopener">Applied tutorial</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/language/functions">Functions</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-6" href="#sidenav-1-6" role="button" aria-expanded="false" aria-controls="sidenav-1-6">Control flow</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-6"><li class="nav-item"><a class="nav-link" href="/language/loops">Loops</a></li><li class="nav-item"><a class="nav-link" href="/language/branches">Branches</a></li><li class="nav-item"><a class="nav-link" href="/language/error-handling">Error handling</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-7" href="#sidenav-1-7" role="button" aria-expanded="false" aria-controls="sidenav-1-7">Classes & objects</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-7"><li class="nav-item"><a class="nav-link" href="/language/classes">Classes</a></li><li class="nav-item"><a class="nav-link" href="/language/constructors">Constructors</a></li><li class="nav-item"><a class="nav-link" href="/language/methods">Methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extend">Extend a class</a></li><li class="nav-item"><a class="nav-link" href="/language/mixins">Mixins</a></li><li class="nav-item"><a class="nav-link" href="/language/enums">Enums</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-methods">Extension methods</a></li><li class="nav-item"><a class="nav-link" href="/language/extension-types">Extension types</a></li><li class="nav-item"><a class="nav-link" href="/language/callable-objects">Callable objects</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-8" href="#sidenav-1-8" role="button" aria-expanded="false" aria-controls="sidenav-1-8">Class modifiers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-8"><li class="nav-item"><a class="nav-link" href="/language/class-modifiers">Overview & usage</a></li><li class="nav-item"><a class="nav-link" href="/language/class-modifiers-for-apis">Class modifiers for API maintainers</a></li><li class="nav-item"><a class="nav-link" href="/language/modifier-reference">Reference</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-9" href="#sidenav-1-9" role="button" aria-expanded="false" aria-controls="sidenav-1-9">Concurrency</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-9"><li class="nav-item"><a class="nav-link" href="/language/concurrency">Overview</a></li><li class="nav-item"><a class="nav-link" href="/language/async">Asynchronous support</a></li><li class="nav-item"><a class="nav-link" href="/language/isolates">Isolates</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-1-10" href="#sidenav-1-10" role="button" aria-expanded="false" aria-controls="sidenav-1-10">Null safety</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-1-10"><li class="nav-item"><a class="nav-link" href="/null-safety">Sound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/migration-guide">Migrating to null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/understanding-null-safety">Understanding null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/unsound-null-safety">Unsound null safety</a></li><li class="nav-item"><a class="nav-link" href="/null-safety/faq">FAQ</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-2" role="button" aria-expanded="false" aria-controls="sidenav-2">Core libraries</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2"><li class="nav-item"><a class="nav-link" href="/libraries">Overview</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-core">dart:core</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-async">dart:async</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-math">dart:math</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-convert">dart:convert</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-io">dart:io</a></li><li class="nav-item"><a class="nav-link" href="/libraries/dart-html">dart:html</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/libraries/collections/iterables">Iterable collections</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-2-10" href="#sidenav-2-10" role="button" aria-expanded="false" aria-controls="sidenav-2-10">Asynchronous programming</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-2-10"><li class="nav-item"><a class="nav-link" href="/libraries/async/async-await">Tutorial</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/futures-error-handling">Futures and error handling</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/using-streams">Using streams</a></li><li class="nav-item"><a class="nav-link" href="/libraries/async/creating-streams">Creating streams</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link active collapsible" data-toggle="collapse" href="#sidenav-3" role="button" aria-expanded="true" aria-controls="sidenav-3">Effective Dart</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-3"><li class="nav-item"><a class="nav-link" href="/effective-dart">Overview</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/style">Style</a></li><li class="nav-item"><a class="nav-link active" href="/effective-dart/documentation">Documentation</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/effective-dart/design">Design</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-4" role="button" aria-expanded="false" aria-controls="sidenav-4">Packages</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4"><li class="nav-item"><a class="nav-link" href="/tools/pub/packages">How to use packages</a></li><li class="nav-item"><a class="nav-link" href="/resources/useful-packages">Commonly used packages</a></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/create-packages">Creating packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/publishing">Publishing packages</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/writing-package-pages">Writing package pages</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-4-6" href="#sidenav-4-6" role="button" aria-expanded="false" aria-controls="sidenav-4-6">Package reference</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-4-6"><li class="nav-item"><a class="nav-link" href="/tools/pub/dependencies">Dependencies</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/package-layout">Package layout conventions</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/environment-variables">Pub environment variables</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/pubspec">Pubspec file</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/troubleshoot">Troubleshooting pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/verified-publishers">Verified publishers</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/security-advisories">Security advisories</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/versioning">Versioning</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/custom-package-repositories">Custom package repositories</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/libraries/private-files">What not to commit</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-5" role="button" aria-expanded="false" aria-controls="sidenav-5">Development</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5"><li class="nav-item"><a class="nav-link" href="/guides/json">JSON</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/numbers">Number representation</a></li><li class="nav-item"><a class="nav-link" href="/resources/google-apis">Google APIs</a></li><li class="nav-item"><a class="nav-link" href="/multiplatform-apps">Multi-platform apps</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-5" href="#sidenav-5-5" role="button" aria-expanded="false" aria-controls="sidenav-5-5">Command-line & server apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-5"><li class="nav-item"><a class="nav-link" href="/server">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/cmdline">Write command-line apps</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/fetch-data">Fetch data from the internet</a></li><li class="nav-item"><a class="nav-link" href="/tutorials/server/httpserver">Write HTTP servers</a></li><li class="nav-item"><a class="nav-link" href="/server/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/server/google-cloud">Google Cloud</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-5-6" href="#sidenav-5-6" role="button" aria-expanded="false" aria-controls="sidenav-5-6">Web apps</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-5-6"><li class="nav-item"><a class="nav-link" href="/web">Overview</a></li><li class="nav-item"><a class="nav-link" href="/web/get-started">Get started</a></li><li class="nav-item"><a class="nav-link" href="/web/deployment">Deployment</a></li><li class="nav-item"><a class="nav-link" href="/web/libraries">Libraries & packages</a></li><li class="nav-item"><a class="nav-link" href="/web/wasm">Wasm compilation</a></li></ul></li><li class="nav-item"><a class="nav-link" href="/guides/environment-declarations">Environment declarations</a></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-6" role="button" aria-expanded="false" aria-controls="sidenav-6">Interoperability</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6"><li class="nav-item"><a class="nav-link" href="/interop/c-interop">C interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/objective-c-interop">Objective-C & Swift interop</a></li><li class="nav-item"><a class="nav-link" href="/interop/java-interop">Java & Kotlin interop</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-6-4" href="#sidenav-6-4" role="button" aria-expanded="false" aria-controls="sidenav-6-4">JavaScript interop</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-6-4"><li class="nav-item"><a class="nav-link" href="/interop/js-interop">Overview</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/usage">Usage</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/js-types">JS types</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/tutorials">Tutorials</a></li><li class="nav-item"><a class="nav-link" href="/interop/js-interop/past-js-interop">Past JS interop</a></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/interop/js-interop/package-web">Web interop</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-7" role="button" aria-expanded="false" aria-controls="sidenav-7">Tools & techniques</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7"><li class="nav-item"><a class="nav-link" href="/tools">Overview</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2" href="#sidenav-7-2" role="button" aria-expanded="false" aria-controls="sidenav-7-2">Editors & debuggers</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2"><li class="nav-item"><a class="nav-link" href="/tools/jetbrains-plugin">IntelliJ & Android Studio</a></li><li class="nav-item"><a class="nav-link" href="/tools/vs-code">VS Code</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-devtools">Dart DevTools</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-2-4" href="#sidenav-7-2-4" role="button" aria-expanded="false" aria-controls="sidenav-7-2-4">DartPad</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-2-4"><li class="nav-item"><a class="nav-link" href="/tools/dartpad">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartpad/troubleshoot">Troubleshooting DartPad</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-3" href="#sidenav-7-3" role="button" aria-expanded="false" aria-controls="sidenav-7-3">Command-line tools</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-3"><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-1" href="#sidenav-7-3-1" role="button" aria-expanded="true" aria-controls="sidenav-7-3-1">Dart SDK</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-1"><li class="nav-item"><a class="nav-link" href="/tools/sdk">Overview</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-tool">dart</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-analyze">dart analyze</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-compile">dart compile</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-create">dart create</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-doc">dart doc</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-fix">dart fix</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-format">dart format</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-info">dart info</a></li><li class="nav-item"><a class="nav-link" href="/tools/pub/cmd">dart pub</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-run">dart run</a></li><li class="nav-item"><a class="nav-link" href="/tools/dart-test">dart test</a></li><li class="nav-item"><a class="nav-link" href="/tools/dartaotruntime">dartaotruntime</a></li><li class="nav-item"><a class="nav-link" href="/tools/experiment-flags">Experiment flags</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" data-target="#sidenav-7-3-2" href="#sidenav-7-3-2" role="button" aria-expanded="true" aria-controls="sidenav-7-3-2">Other command-line tools</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-7-3-2"><li class="nav-item"><a class="nav-link" href="/tools/build_runner">build_runner</a></li><li class="nav-item"><a class="nav-link" href="/tools/webdev">webdev</a></li></ul></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-4" href="#sidenav-7-4" role="button" aria-expanded="false" aria-controls="sidenav-7-4">Static analysis</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-4"><li class="nav-item"><a class="nav-link" href="/tools/analysis">Customizing static analysis</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/sound-problems">Fixing common type problems</a></li><li class="nav-item"><a class="nav-link" href="/tools/non-promotion-reasons">Fixing type promotion failures</a></li><li class="nav-item"><a class="nav-link" href="/tools/linter-rules">Linter rules</a></li><li class="nav-item"><a class="nav-link" href="/tools/diagnostic-messages">Diagnostic messages</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-7-5" href="#sidenav-7-5" role="button" aria-expanded="false" aria-controls="sidenav-7-5">Testing & optimization</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-7-5"><li class="nav-item"><a class="nav-link" href="/guides/testing">Testing</a></li><li class="nav-item"><a class="nav-link" href="/web/debugging">Debugging web apps</a></li></ul></li></ul></li><li aria-hidden="true"><div class="sidebar-primary-divider"></div></li><li class="nav-item"><a class="nav-link collapsed collapsible" data-toggle="collapse" href="#sidenav-9" role="button" aria-expanded="false" aria-controls="sidenav-9">Resources</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9"><li class="nav-item"><a class="nav-link" href="/resources/dart-cheatsheet">Language cheatsheet</a></li><li class="nav-item"><a class="nav-link" href="/resources/breaking-changes">Breaking changes</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/evolution">Language evolution</a></li><li class="nav-item"><a class="nav-link" href="/guides/language/spec">Language specification</a></li><li class="nav-item"><a class="nav-link" href="/resources/dart-3-migration">Dart 3 migration guide</a></li><li class="nav-item"><a class="nav-link collapsible collapsed" data-toggle="collapse" data-target="#sidenav-9-6" href="#sidenav-9-6" role="button" aria-expanded="false" aria-controls="sidenav-9-6">Coming from ...</a><ul class="nav flex-column flex-nowrap collapse" id="sidenav-9-6"><li class="nav-item"><a class="nav-link" href="/resources/coming-from/js-to-dart">JavaScript to Dart</a></li><li class="nav-item"><a class="nav-link" href="/resources/coming-from/swift-to-dart">Swift to Dart</a></li></ul></li><div class="dropdown-divider"></div><li class="nav-item"><a class="nav-link" href="/resources/faq">FAQ</a></li><li class="nav-item"><a class="nav-link" href="/resources/glossary">Glossary</a></li><li class="nav-item"><a class="nav-link" href="/resources/books">Books</a></li><li class="nav-item"><a class="nav-link" href="/resources/videos">Videos</a></li><li class="nav-item"><a class="nav-link" href="/tutorials">Tutorials</a></li></ul></li><li class="nav-item"><a class="nav-link collapsible" data-toggle="collapse" href="#sidenav-10" role="button" aria-expanded="true" aria-controls="sidenav-10">Related sites</a><ul class="nav flex-column flex-nowrap collapse show" id="sidenav-10"><li class="nav-item"><a class="nav-link" href="https://api.dart.dev" target="_blank" rel="noopener">API reference</a></li><li class="nav-item"><a class="nav-link" href="https://medium.com/dartlang" target="_blank" rel="noopener">Blog</a></li><li class="nav-item"><a class="nav-link" href="https://dartpad.dev" target="_blank" rel="noopener">DartPad (online editor)</a></li><li class="nav-item"><a class="nav-link" href="https://flutter.dev" target="_blank" rel="noopener">Flutter</a></li><li class="nav-item"><a class="nav-link" href="https://pub.dev" target="_blank" rel="noopener">Package site</a></li></ul></li></ul></div></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="#comments">Comments</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-format-comments-like-sentences">DO format comments like sentences</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#dont-use-block-comments-for-documentation">DON'T use block comments for documentation</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#doc-comments">Doc comments</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#do-use-doc-comments-to-document-members-and-types">DO use /// doc comments to document members and types</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-writing-doc-comments-for-public-apis">PREFER writing doc comments for public APIs</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-writing-a-library-level-doc-comment">CONSIDER writing a library-level doc comment</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-writing-doc-comments-for-private-apis">CONSIDER writing doc comments for private APIs</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-start-doc-comments-with-a-single-sentence-summary">DO start doc comments with a single-sentence summary</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#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 class="toc-entry nav-item"><a class="nav-link" href="#avoid-redundancy-with-the-surrounding-context">AVOID redundancy with the surrounding context</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-starting-function-or-method-comments-with-third-person-verbs">PREFER starting function or method comments with third-person verbs</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#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 class="toc-entry nav-item"><a class="nav-link" href="#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 class="toc-entry nav-item"><a class="nav-link" href="#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 class="toc-entry nav-item"><a class="nav-link" href="#prefer-starting-library-or-type-comments-with-noun-phrases">PREFER starting library or type comments with noun phrases</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#consider-including-code-samples-in-doc-comments">CONSIDER including code samples in doc comments</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#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 class="toc-entry nav-item"><a class="nav-link" href="#do-use-prose-to-explain-parameters-return-values-and-exceptions">DO use prose to explain parameters, return values, and exceptions</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#do-put-doc-comments-before-metadata-annotations">DO put doc comments before metadata annotations</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#markdown">Markdown</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-markdown-excessively">AVOID using markdown excessively</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-using-html-for-formatting">AVOID using HTML for formatting</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-backtick-fences-for-code-blocks">PREFER backtick fences for code blocks</a></li></ul></li><li class="toc-entry nav-item"><a class="nav-link" href="#writing">Writing</a><ul class="nav"><li class="toc-entry nav-item"><a class="nav-link" href="#prefer-brevity">PREFER brevity</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#avoid-abbreviations-and-acronyms-unless-they-are-obvious">AVOID abbreviations and acronyms unless they are obvious</a></li><li class="toc-entry nav-item"><a class="nav-link" href="#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></li></ul></div><article><div class="content"><nav id="subnav"><ul><li class="previous"><a href="/effective-dart/style">&lang;  Style</a></li><li class="next"><a href="/effective-dart/usage">Usage  &rang;</a></li></ul></nav><div id="site-content-title"><h1>Effective Dart: Documentation</h1></div><div id="site-toc--inline" class="site-toc toc-collapsible toc-collapsed"><header class="site-toc__title">Contents <span class="site-toc--inline__toggle toc-toggle-down"><i class="material-symbols">keyboard_arrow_down</i></span> <span class="site-toc--inline__toggle toc-toggle-up"><i class="material-symbols">keyboard_arrow_up</i></span></header><ul class="section-nav"><li class="toc-entry"><a href="#comments">Comments</a><ul><li class="toc-entry"><a href="#do-format-comments-like-sentences">DO format comments like sentences</a></li><li class="toc-entry"><a href="#dont-use-block-comments-for-documentation">DON'T use block comments for documentation</a></li></ul></li><li class="toc-entry"><a href="#doc-comments">Doc comments</a><ul><li class="toc-entry"><a href="#do-use-doc-comments-to-document-members-and-types">DO use /// doc comments to document members and types</a></li><li class="toc-entry"><a href="#prefer-writing-doc-comments-for-public-apis">PREFER writing doc comments for public APIs</a></li><li class="toc-entry"><a href="#consider-writing-a-library-level-doc-comment">CONSIDER writing a library-level doc comment</a></li><li class="toc-entry"><a href="#consider-writing-doc-comments-for-private-apis">CONSIDER writing doc comments for private APIs</a></li><li class="toc-entry"><a href="#do-start-doc-comments-with-a-single-sentence-summary">DO start doc comments with a single-sentence summary</a></li><li class="toc-entry"><a href="#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 class="toc-entry"><a href="#avoid-redundancy-with-the-surrounding-context">AVOID redundancy with the surrounding context</a></li><li class="toc-entry"><a href="#prefer-starting-function-or-method-comments-with-third-person-verbs">PREFER starting function or method comments with third-person verbs</a></li><li class="toc-entry"><a href="#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 class="toc-entry"><a href="#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 class="toc-entry"><a href="#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 class="toc-entry"><a href="#prefer-starting-library-or-type-comments-with-noun-phrases">PREFER starting library or type comments with noun phrases</a></li><li class="toc-entry"><a href="#consider-including-code-samples-in-doc-comments">CONSIDER including code samples in doc comments</a></li><li class="toc-entry"><a href="#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 class="toc-entry"><a href="#do-use-prose-to-explain-parameters-return-values-and-exceptions">DO use prose to explain parameters, return values, and exceptions</a></li><li class="toc-entry"><a href="#do-put-doc-comments-before-metadata-annotations">DO put doc comments before metadata annotations</a></li></ul></li><li class="toc-entry"><a href="#markdown">Markdown</a><ul><li class="toc-entry"><a href="#avoid-using-markdown-excessively">AVOID using markdown excessively</a></li><li class="toc-entry"><a href="#avoid-using-html-for-formatting">AVOID using HTML for formatting</a></li><li class="toc-entry"><a href="#prefer-backtick-fences-for-code-blocks">PREFER backtick fences for code blocks</a></li></ul></li><li class="toc-entry"><a href="#writing">Writing</a><ul><li class="toc-entry"><a href="#prefer-brevity">PREFER brevity</a></li><li class="toc-entry"><a href="#avoid-abbreviations-and-acronyms-unless-they-are-obvious">AVOID abbreviations and acronyms unless they are obvious</a></li><li class="toc-entry"><a href="#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></li></ul><span class="site-toc--inline__toggle toc-toggle-more-items"><i class="material-symbols">more_horiz</i></span></div> <?code-excerpt path-base="misc/lib/effective_dart"?> <p>It's easy to think your code is obvious today without realizing how much you rely on context already in your head. People new to your code, and even your forgetful future self won't have that context. A concise, accurate comment only takes a few seconds to write but can save one of those people hours of time.</p><p>We all know code should be self-documenting and not all comments are helpful. But the reality is that most of us don't write as many comments as we should. It's like exercise: you technically <em>can</em> do too much, but it's a lot more likely that you're doing too little. Try to step it up.</p><div class="header-wrapper"><h2 id="comments">Comments</h2><a class="heading-link" href="#comments" aria-label="Link to 'Comments' section">#</a></div><p>The following tips apply to comments that you don't want included in the generated documentation.</p><div class="header-wrapper"><h3 id="do-format-comments-like-sentences">DO format comments like sentences</h3><a class="heading-link" href="#do-format-comments-like-sentences" aria-label="Link to 'DO format comments like sentences' section">#</a></div> <?code-excerpt "docs_good.dart (comments-like-sentences)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// Not if anything comes before it.</span></span> <span class="line"><span style="color:#D43324">if</span><span style="color:#222222"> (_chunks.isNotEmpty) </span><span style="color:#D43324">return</span><span style="color:#11796D"> false</span><span style="color:#222222">;</span></span></code></pre></div></div><p>Capitalize the first word unless it's a case-sensitive identifier. End it with a period (or "!" or "?", I suppose). This is true for all comments: doc comments, inline stuff, even TODOs. Even if it's a sentence fragment.</p><div class="header-wrapper"><h3 id="dont-use-block-comments-for-documentation">DON'T use block comments for documentation</h3><a class="heading-link" href="#dont-use-block-comments-for-documentation" aria-label="Link to 'DON'T use block comments for documentation' section">#</a></div> <?code-excerpt "docs_good.dart (block-comments)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> greet</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> name) {</span></span> <span class="line"><span style="color:#6E6E70"> // Assume we have a valid name.</span></span> <span class="line"><span style="color:#6200EE"> print</span><span style="color:#222222">(</span><span style="color:#11796D">'Hi, </span><span style="color:#11796D">$</span><span style="color:#222222">name</span><span style="color:#11796D">!'</span><span style="color:#222222">);</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (block-comments)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> greet</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> name) {</span></span> <span class="line"><span style="color:#6E6E70"> /* Assume we have a valid name. */</span></span> <span class="line"><span style="color:#6200EE"> print</span><span style="color:#222222">(</span><span style="color:#11796D">'Hi, </span><span style="color:#11796D">$</span><span style="color:#222222">name</span><span style="color:#11796D">!'</span><span style="color:#222222">);</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><p>You can use a block comment (<code>/* ... */</code>) to temporarily comment out a section of code, but all other comments should use <code>//</code>.</p><div class="header-wrapper"><h2 id="doc-comments">Doc comments</h2><a class="heading-link" href="#doc-comments" aria-label="Link to 'Doc comments' section">#</a></div><p>Doc comments are especially handy because <a href="/tools/dart-doc"><code>dart doc</code></a> parses them and generates <a href="https://api.dart.dev">beautiful doc pages</a> from them. A doc comment is any comment that appears before a declaration and uses the special <code>///</code> syntax that <code>dart doc</code> looks for.</p><div class="header-wrapper"><h3 id="do-use-doc-comments-to-document-members-and-types">DO use <code>///</code> doc comments to document members and types</h3><a class="heading-link" href="#do-use-doc-comments-to-document-members-and-types" aria-label="Link to 'DO use /// doc comments to document members and types' section">#</a></div><p class="linter-rule">Linter rule: <a href="/tools/linter-rules/slash_for_doc_comments">slash_for_doc_comments</a></p><p>Using a doc comment instead of a regular comment enables <a href="/tools/dart-doc"><code>dart doc</code></a> to find it and generate documentation for it.</p> <?code-excerpt "docs_good.dart (use-doc-comments)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// The number of characters in this chunk when unsplit.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#D43324"> get</span><span style="color:#222222"> length => ...</span></span></code></pre></div></div><?code-excerpt "docs_good.dart (use-doc-comments)" replace="/^\///g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">// The number of characters in this chunk when unsplit.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#D43324"> get</span><span style="color:#222222"> length => ...</span></span></code></pre></div></div><p>For historical reasons, <code>dart doc</code> supports two syntaxes of doc comments: <code>///</code> ("C# style") and <code>/** ... */</code> ("JavaDoc style"). We prefer <code>///</code> because it's more compact. <code>/**</code> and <code>*/</code> add two content-free lines to a multiline doc comment. The <code>///</code> syntax is also easier to read in some situations, such as when a doc comment contains a bulleted list that uses <code>*</code> to mark list items.</p><p>If you stumble onto code that still uses the JavaDoc style, consider cleaning it up.</p><div class="header-wrapper"><h3 id="prefer-writing-doc-comments-for-public-apis">PREFER writing doc comments for public APIs</h3><a class="heading-link" href="#prefer-writing-doc-comments-for-public-apis" aria-label="Link to 'PREFER writing doc comments for public APIs' section">#</a></div><p class="linter-rule">Linter rules: <a href="/tools/linter-rules/package_api_docs">package_api_docs</a>, <a href="/tools/linter-rules/public_member_api_docs">public_member_api_docs</a></p><p>You don't have to document every single library, top-level variable, type, and member, but you should document most of them.</p><div class="header-wrapper"><h3 id="consider-writing-a-library-level-doc-comment">CONSIDER writing a library-level doc comment</h3><a class="heading-link" href="#consider-writing-a-library-level-doc-comment" aria-label="Link to 'CONSIDER writing a library-level doc comment' section">#</a></div><p>Unlike languages like Java where the class is the only unit of program organization, in Dart, a library is itself an entity that users work with directly, import, and think about. That makes the <code>library</code> directive a great place for documentation that introduces the reader to the main concepts and functionality provided within. Consider including:</p><ul><li>A single-sentence summary of what the library is for.</li><li>Explanations of terminology used throughout the library.</li><li>A couple of complete code samples that walk through using the API.</li><li>Links to the most important or most commonly used classes and functions.</li><li>Links to external references on the domain the library is concerned with.</li></ul><p>To document a library, place a doc comment before the <code>library</code> directive and any annotations that might be attached at the start of the file.</p> <?code-excerpt "docs_good.dart (library-doc)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// A really great test library.</span></span> <span class="line"><span style="color:#D43324">@TestOn</span><span style="color:#222222">(</span><span style="color:#11796D">'browser'</span><span style="color:#222222">)</span></span> <span class="line"><span style="color:#D43324">library</span><span style="color:#222222">;</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="consider-writing-doc-comments-for-private-apis">CONSIDER writing doc comments for private APIs</h3><a class="heading-link" href="#consider-writing-doc-comments-for-private-apis" aria-label="Link to 'CONSIDER writing doc comments for private APIs' section">#</a></div><p>Doc comments aren't just for external consumers of your library's public API. They can also be helpful for understanding private members that are called from other parts of the library.</p><div class="header-wrapper"><h3 id="do-start-doc-comments-with-a-single-sentence-summary">DO start doc comments with a single-sentence summary</h3><a class="heading-link" href="#do-start-doc-comments-with-a-single-sentence-summary" aria-label="Link to 'DO start doc comments with a single-sentence summary' section">#</a></div><p>Start your doc comment with a brief, user-centric description ending with a period. A sentence fragment is often sufficient. Provide just enough context for the reader to orient themselves and decide if they should keep reading or look elsewhere for the solution to their problem.</p> <?code-excerpt "docs_good.dart (first-sentence)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Deletes the file at </span><span style="color:#222222">[path]</span><span style="color:#6E6E70"> from the file system.</span></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> delete</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> path) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (first-sentence)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Depending on the state of the file system and the user's permissions,</span></span> <span class="line"><span style="color:#6E6E70">/// certain operations may or may not be possible. If there is no file at</span></span> <span class="line"><span style="color:#6E6E70">/// </span><span style="color:#222222">[path]</span><span style="color:#6E6E70"> or it can't be accessed, this function throws either </span><span style="color:#222222">[IOError]</span></span> <span class="line"><span style="color:#6E6E70">/// or </span><span style="color:#222222">[PermissionError]</span><span style="color:#6E6E70">, respectively. Otherwise, this deletes the file.</span></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> delete</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> path) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#do-separate-the-first-sentence-of-a-doc-comment-into-its-own-paragraph" aria-label="Link to 'DO separate the first sentence of a doc comment into its own paragraph' section">#</a></div><p>Add a blank line after the first sentence to split it out into its own paragraph. If more than a single sentence of explanation is useful, put the rest in later paragraphs.</p><p>This helps you write a tight first sentence that summarizes the documentation. Also, tools like <code>dart doc</code> use the first paragraph as a short summary in places like lists of classes and members.</p> <?code-excerpt "docs_good.dart (first-sentence-a-paragraph)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Deletes the file at </span><span style="color:#222222">[path]</span><span style="color:#6E6E70">.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// Throws an </span><span style="color:#222222">[IOError]</span><span style="color:#6E6E70"> if the file could not be found. Throws a</span></span> <span class="line"><span style="color:#6E6E70">/// </span><span style="color:#222222">[PermissionError]</span><span style="color:#6E6E70"> if the file is present but could not be deleted.</span></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> delete</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> path) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (first-sentence-a-paragraph)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Deletes the file at </span><span style="color:#222222">[path]</span><span style="color:#6E6E70">. Throws an </span><span style="color:#222222">[IOError]</span><span style="color:#6E6E70"> if the file could not</span></span> <span class="line"><span style="color:#6E6E70">/// be found. Throws a </span><span style="color:#222222">[PermissionError]</span><span style="color:#6E6E70"> if the file is present but could</span></span> <span class="line"><span style="color:#6E6E70">/// not be deleted.</span></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> delete</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> path) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="avoid-redundancy-with-the-surrounding-context">AVOID redundancy with the surrounding context</h3><a class="heading-link" href="#avoid-redundancy-with-the-surrounding-context" aria-label="Link to 'AVOID redundancy with the surrounding context' section">#</a></div><p>The reader of a class's doc comment can clearly see the name of the class, what interfaces it implements, etc. When reading docs for a member, the signature is right there, and the enclosing class is obvious. None of that needs to be spelled out in the doc comment. Instead, focus on explaining what the reader <em>doesn't</em> already know.</p> <?code-excerpt "docs_good.dart (redundant)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> RadioButtonWidget</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Widget</span><span style="color:#222222"> {</span></span> <span class="line"><span style="color:#6E6E70"> /// Sets the tooltip to </span><span style="color:#222222">[lines]</span><span style="color:#6E6E70">, which should have been word wrapped using</span></span> <span class="line"><span style="color:#6E6E70"> /// the current font.</span></span> <span class="line"><span style="color:#D43324"> void</span><span style="color:#6200EE"> tooltip</span><span style="color:#222222">(</span><span style="color:#0468D7">List</span><span style="color:#222222"><</span><span style="color:#0468D7">String</span><span style="color:#222222">> lines) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222"> }</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (redundant)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> RadioButtonWidget</span><span style="color:#D43324"> extends</span><span style="color:#0468D7"> Widget</span><span style="color:#222222"> {</span></span> <span class="line"><span style="color:#6E6E70"> /// Sets the tooltip for this radio button widget to the list of strings in</span></span> <span class="line"><span style="color:#6E6E70"> /// </span><span style="color:#222222">[lines]</span><span style="color:#6E6E70">.</span></span> <span class="line"><span style="color:#D43324"> void</span><span style="color:#6200EE"> tooltip</span><span style="color:#222222">(</span><span style="color:#0468D7">List</span><span style="color:#222222"><</span><span style="color:#0468D7">String</span><span style="color:#222222">> lines) {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222"> }</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><p>If you really don't have anything interesting to say that can't be inferred from the declaration itself, then omit the doc comment. It's better to say nothing than waste a reader's time telling them something they already know.</p><div class="header-wrapper"><h3 id="prefer-starting-function-or-method-comments-with-third-person-verbs">PREFER starting function or method comments with third-person verbs</h3><a class="heading-link" href="#prefer-starting-function-or-method-comments-with-third-person-verbs" aria-label="Link to 'PREFER starting function or method comments with third-person verbs' section">#</a></div><p>The doc comment should focus on what the code <em>does</em>.</p> <?code-excerpt "docs_good.dart (third-person)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Returns </span><span style="color:#222222">`true`</span><span style="color:#6E6E70"> if every element satisfies the </span><span style="color:#222222">[predicate]</span><span style="color:#6E6E70">.</span></span> <span class="line"><span style="color:#0468D7">bool</span><span style="color:#6200EE"> all</span><span style="color:#222222">(</span><span style="color:#0468D7">bool</span><span style="color:#6200EE"> predicate</span><span style="color:#222222">(</span><span style="color:#0468D7">T</span><span style="color:#222222"> element)) => ...</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">/// Starts the stopwatch if not already running.</span></span> <span class="line"><span style="color:#D43324">void</span><span style="color:#6200EE"> start</span><span style="color:#222222">() {</span></span> <span class="line"><span style="color:#222222"> ...</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#prefer-starting-a-non-boolean-variable-or-property-comment-with-a-noun-phrase" aria-label="Link to 'PREFER starting a non-boolean variable or property comment with a noun phrase' section">#</a></div><p>The doc comment should stress what the property <em>is</em>. This is true even for getters which may do calculation or other work. What the caller cares about is the <em>result</em> of that work, not the work itself.</p> <?code-excerpt "docs_good.dart (noun-phrases-for-non-boolean-var-etc)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// The current day of the week, where </span><span style="color:#222222">`0`</span><span style="color:#6E6E70"> is Sunday.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#222222"> weekday;</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">/// The number of checked buttons on the page.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#D43324"> get</span><span style="color:#222222"> checkedCount => ...</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#prefer-starting-a-boolean-variable-or-property-comment-with-whether-followed-by-a-noun-or-gerund-phrase" aria-label="Link to 'PREFER starting a boolean variable or property comment with "Whether" followed by a noun or gerund phrase' section">#</a></div><p>The doc comment should clarify the states this variable represents. This is true even for getters which may do calculation or other work. What the caller cares about is the <em>result</em> of that work, not the work itself.</p> <?code-excerpt "docs_good.dart (noun-phrases-for-boolean-var-etc)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Whether the modal is currently displayed to the user.</span></span> <span class="line"><span style="color:#0468D7">bool</span><span style="color:#222222"> isVisible;</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">/// Whether the modal should confirm the user's intent on navigation.</span></span> <span class="line"><span style="color:#0468D7">bool</span><span style="color:#D43324"> get</span><span style="color:#222222"> shouldConfirm => ...</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">/// Whether resizing the current browser window will also resize the modal.</span></span> <span class="line"><span style="color:#0468D7">bool</span><span style="color:#D43324"> get</span><span style="color:#222222"> canResize => ...</span></span></code></pre></div></div><aside class="alert alert-info"><div class="alert-header"><i class="material-symbols" aria-hidden="true">info</i> <span>Note</span></div><div class="alert-content"><p>This guideline intentionally doesn't include using "Whether or not". In many cases, usage of "or not" with "whether" is superfluous and can be omitted, especially when used in this context.</p></div></aside><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#dont-write-documentation-for-both-the-getter-and-setter-of-a-property" aria-label="Link to 'DON'T write documentation for both the getter and setter of a property' section">#</a></div><p>If a property has both a getter and a setter, then create a doc comment for only one of them. <code>dart doc</code> treats the getter and setter like a single field, and if both the getter and the setter have doc comments, then <code>dart doc</code> discards the setter's doc comment.</p> <?code-excerpt "docs_good.dart (getter-and-setter)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// The pH level of the water in the pool.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// Ranges from 0-14, representing acidic to basic, with 7 being neutral.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#D43324"> get</span><span style="color:#222222"> phLevel => ...</span></span> <span class="line"><span style="color:#D43324">set</span><span style="color:#6200EE"> phLevel</span><span style="color:#222222">(</span><span style="color:#0468D7">int</span><span style="color:#222222"> level) => ...</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (getter-and-setter)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// The depth of the water in the pool, in meters.</span></span> <span class="line"><span style="color:#0468D7">int</span><span style="color:#D43324"> get</span><span style="color:#222222"> waterDepth => ...</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70">/// Updates the water depth to a total of </span><span style="color:#222222">[meters]</span><span style="color:#6E6E70"> in height.</span></span> <span class="line"><span style="color:#D43324">set</span><span style="color:#6200EE"> waterDepth</span><span style="color:#222222">(</span><span style="color:#0468D7">int</span><span style="color:#222222"> meters) => ...</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="prefer-starting-library-or-type-comments-with-noun-phrases">PREFER starting library or type comments with noun phrases</h3><a class="heading-link" href="#prefer-starting-library-or-type-comments-with-noun-phrases" aria-label="Link to 'PREFER starting library or type comments with noun phrases' section">#</a></div><p>Doc comments for classes are often the most important documentation in your program. They describe the type's invariants, establish the terminology it uses, and provide context to the other doc comments for the class's members. A little extra effort here can make all of the other members simpler to document.</p> <?code-excerpt "docs_good.dart (noun-phrases-for-type-or-lib)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// A chunk of non-breaking output text terminated by a hard or soft newline.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ...</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Chunk</span><span style="color:#222222"> { ... }</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="consider-including-code-samples-in-doc-comments">CONSIDER including code samples in doc comments</h3><a class="heading-link" href="#consider-including-code-samples-in-doc-comments" aria-label="Link to 'CONSIDER including code samples in doc comments' section">#</a></div> <?code-excerpt "docs_good.dart (code-sample)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Returns the lesser of two numbers.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ```dart</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> min(5, 3) == 3</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#6E6E70"> ```</span></span> <span class="line"><span style="color:#0468D7">num</span><span style="color:#6200EE"> min</span><span style="color:#222222">(</span><span style="color:#0468D7">num</span><span style="color:#222222"> a, </span><span style="color:#0468D7">num</span><span style="color:#222222"> b) => ...</span></span></code></pre></div></div><p>Humans are great at generalizing from examples, so even a single code sample makes an API easier to learn.</p><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#do-use-square-brackets-in-doc-comments-to-refer-to-in-scope-identifiers" aria-label="Link to 'DO use square brackets in doc comments to refer to in-scope identifiers' section">#</a></div><p class="linter-rule">Linter rule: <a href="/tools/linter-rules/comment_references">comment_references</a></p><p>If you surround things like variable, method, or type names in square brackets, then <code>dart doc</code> looks up the name and links to the relevant API docs. Parentheses are optional, but can make it clearer when you're referring to a method or constructor.</p> <?code-excerpt "docs_good.dart (identifiers)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Throws a </span><span style="color:#222222">[StateError]</span><span style="color:#6E6E70"> if ...</span></span> <span class="line"><span style="color:#6E6E70">/// similar to </span><span style="color:#222222">[anotherMethod()]</span><span style="color:#6E6E70">, but ...</span></span></code></pre></div></div><p>To link to a member of a specific class, use the class name and member name, separated by a dot:</p> <?code-excerpt "docs_good.dart (member)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Similar to </span><span style="color:#222222">[Duration.inDays]</span><span style="color:#6E6E70">, but handles fractional days.</span></span></code></pre></div></div><p>The dot syntax can also be used to refer to named constructors. For the unnamed constructor, use <code>.new</code> after the class name:</p> <?code-excerpt "docs_good.dart (ctor)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// To create a point, call </span><span style="color:#222222">[Point.new]</span><span style="color:#6E6E70"> or use </span><span style="color:#222222">[Point.polar]</span><span style="color:#6E6E70"> to ...</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="do-use-prose-to-explain-parameters-return-values-and-exceptions">DO use prose to explain parameters, return values, and exceptions</h3><a class="heading-link" href="#do-use-prose-to-explain-parameters-return-values-and-exceptions" aria-label="Link to 'DO use prose to explain parameters, return values, and exceptions' section">#</a></div><p>Other languages use verbose tags and sections to describe what the parameters and returns of a method are.</p> <?code-excerpt "docs_bad.dart (no-annotations)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Defines a flag with the given name and abbreviation.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// @param name The name of the flag.</span></span> <span class="line"><span style="color:#6E6E70">/// @param abbr The abbreviation for the flag.</span></span> <span class="line"><span style="color:#6E6E70">/// @returns The new flag.</span></span> <span class="line"><span style="color:#6E6E70">/// @throws ArgumentError If there is already an option with</span></span> <span class="line"><span style="color:#6E6E70">/// the given name or abbreviation.</span></span> <span class="line"><span style="color:#0468D7">Flag</span><span style="color:#6200EE"> addFlag</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> name, </span><span style="color:#0468D7">String</span><span style="color:#222222"> abbr) => ...</span></span></code></pre></div></div><p>The convention in Dart is to integrate that into the description of the method and highlight parameters using square brackets.</p> <?code-excerpt "docs_good.dart (no-annotations)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// Defines a flag.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// Throws an </span><span style="color:#222222">[ArgumentError]</span><span style="color:#6E6E70"> if there is already an option named </span><span style="color:#222222">[name]</span><span style="color:#6E6E70"> or</span></span> <span class="line"><span style="color:#6E6E70">/// there is already an option using abbreviation </span><span style="color:#222222">[abbr]</span><span style="color:#6E6E70">. Returns the new flag.</span></span> <span class="line"><span style="color:#0468D7">Flag</span><span style="color:#6200EE"> addFlag</span><span style="color:#222222">(</span><span style="color:#0468D7">String</span><span style="color:#222222"> name, </span><span style="color:#0468D7">String</span><span style="color:#222222"> abbr) => ...</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="do-put-doc-comments-before-metadata-annotations">DO put doc comments before metadata annotations</h3><a class="heading-link" href="#do-put-doc-comments-before-metadata-annotations" aria-label="Link to 'DO put doc comments before metadata annotations' section">#</a></div> <?code-excerpt "docs_good.dart (doc-before-meta)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// A button that can be flipped on and off.</span></span> <span class="line"><span style="color:#D43324">@Component</span><span style="color:#222222">(selector: </span><span style="color:#11796D">'toggle'</span><span style="color:#222222">)</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> ToggleComponent</span><span style="color:#222222"> {}</span></span></code></pre></div></div><?code-excerpt "docs_bad.dart (doc-before-meta)" replace="/\n\n/\n/g"?> <div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">@Component</span><span style="color:#222222">(selector: </span><span style="color:#11796D">'toggle'</span><span style="color:#222222">)</span></span> <span class="line"><span style="color:#6E6E70">/// A button that can be flipped on and off.</span></span> <span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> ToggleComponent</span><span style="color:#222222"> {}</span></span></code></pre></div></div><div class="header-wrapper"><h2 id="markdown">Markdown</h2><a class="heading-link" href="#markdown" aria-label="Link to 'Markdown' section">#</a></div><p>You are allowed to use most <a href="https://daringfireball.net/projects/markdown/">markdown</a> formatting in your doc comments and <code>dart doc</code> will process it accordingly using the <a href="https://pub.dev/packages/markdown">markdown package.</a></p><p>There are tons of guides out there already to introduce you to Markdown. Its universal popularity is why we chose it. Here's just a quick example to give you a flavor of what's supported:</p> <?code-excerpt "docs_good.dart (markdown)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// This is a paragraph of regular text.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// This sentence has *two* _emphasized_ words (italics) and **two**</span></span> <span class="line"><span style="color:#6E6E70">/// __strong__ ones (bold).</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// A blank line creates a separate paragraph. It has some </span><span style="color:#222222">`inline code`</span></span> <span class="line"><span style="color:#6E6E70">/// delimited using backticks.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// * Unordered lists.</span></span> <span class="line"><span style="color:#6E6E70">/// * Look like ASCII bullet lists.</span></span> <span class="line"><span style="color:#6E6E70">/// * You can also use </span><span style="color:#222222">`-`</span><span style="color:#6E6E70"> or </span><span style="color:#222222">`+`</span><span style="color:#6E6E70">.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// 1. Numbered lists.</span></span> <span class="line"><span style="color:#6E6E70">/// 2. Are, well, numbered.</span></span> <span class="line"><span style="color:#6E6E70">/// 1. But the values don't matter.</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// * You can nest lists too.</span></span> <span class="line"><span style="color:#6E6E70">/// * They must be indented at least 4 spaces.</span></span> <span class="line"><span style="color:#6E6E70">/// * (Well, 5 including the space after </span><span style="color:#222222">`///`</span><span style="color:#6E6E70">.)</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// Code blocks are fenced in triple backticks:</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ```dart</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> this.code</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> .will</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> .retain(its, formatting);</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#6E6E70"> ```</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// The code language (for syntax highlighting) defaults to Dart. You can</span></span> <span class="line"><span style="color:#6E6E70">/// specify it by putting the name of the language after the opening backticks:</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ```html</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> <h1>HTML is magical!</h1></span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#6E6E70"> ```</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// Links can be:</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// * https://www.just-a-bare-url.com</span></span> <span class="line"><span style="color:#6E6E70">/// * </span><span style="color:#222222">[with the URL inline]</span><span style="color:#6E6E70">(https://google.com)</span></span> <span class="line"><span style="color:#6E6E70">/// * </span><span style="color:#222222">[or separated out][ref link]</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// </span><span style="color:#222222">[ref link]</span><span style="color:#6E6E70">: https://google.com</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// # A Header</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ## A subheader</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ### A subsubheader</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// #### If you need this many levels of headers, you're doing it wrong</span></span></code></pre></div></div><div class="header-wrapper"><h3 id="avoid-using-markdown-excessively">AVOID using markdown excessively</h3><a class="heading-link" href="#avoid-using-markdown-excessively" aria-label="Link to 'AVOID using markdown excessively' section">#</a></div><p>When in doubt, format less. Formatting exists to illuminate your content, not replace it. Words are what matter.</p><div class="header-wrapper"><h3 id="avoid-using-html-for-formatting">AVOID using HTML for formatting</h3><a class="heading-link" href="#avoid-using-html-for-formatting" aria-label="Link to 'AVOID using HTML for formatting' section">#</a></div><p>It <em>may</em> be useful to use it in rare cases for things like tables, but in almost all cases, if it's too complex to express in Markdown, you're better off not expressing it.</p><div class="header-wrapper"><h3 id="prefer-backtick-fences-for-code-blocks">PREFER backtick fences for code blocks</h3><a class="heading-link" href="#prefer-backtick-fences-for-code-blocks" aria-label="Link to 'PREFER backtick fences for code blocks' section">#</a></div><p>Markdown has two ways to indicate a block of code: indenting the code four spaces on each line, or surrounding it in a pair of triple-backtick "fence" lines. The former syntax is brittle when used inside things like Markdown lists where indentation is already meaningful or when the code block itself contains indented code.</p><p>The backtick syntax avoids those indentation woes, lets you indicate the code's language, and is consistent with using backticks for inline code.</p><div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-good"><span class="code-block-tag">good</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// You can use </span><span style="color:#222222">[CodeBlockExample]</span><span style="color:#6E6E70"> like this:</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// ```dart</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> var example = CodeBlockExample();</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#222222"> print(example.isItGreat); // "Yes."</span></span> <span class="line"><span style="color:#6E6E70">///</span><span style="color:#6E6E70"> ```</span></span></code></pre></div></div><div class="code-block-wrapper language-dart"><div class="code-block-body has-tag tag-bad"><span class="code-block-tag">bad</span><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#6E6E70">/// You can use </span><span style="color:#222222">[CodeBlockExample]</span><span style="color:#6E6E70"> like this:</span></span> <span class="line"><span style="color:#6E6E70">///</span></span> <span class="line"><span style="color:#6E6E70">/// var example = CodeBlockExample();</span></span> <span class="line"><span style="color:#6E6E70">/// print(example.isItGreat); // "Yes."</span></span></code></pre></div></div><div class="header-wrapper"><h2 id="writing">Writing</h2><a class="heading-link" href="#writing" aria-label="Link to 'Writing' section">#</a></div><p>We think of ourselves as programmers, but most of the characters in a source file are intended primarily for humans to read. English is the language we code in to modify the brains of our coworkers. As for any programming language, it's worth putting effort into improving your proficiency.</p><p>This section lists a few guidelines for our docs. You can learn more about best practices for technical writing, in general, from articles such as <a href="https://en.wikiversity.org/wiki/Technical_writing_style">Technical writing style</a>.</p><div class="header-wrapper"><h3 id="prefer-brevity">PREFER brevity</h3><a class="heading-link" href="#prefer-brevity" aria-label="Link to 'PREFER brevity' section">#</a></div><p>Be clear and precise, but also terse.</p><div class="header-wrapper"><h3 id="avoid-abbreviations-and-acronyms-unless-they-are-obvious">AVOID abbreviations and acronyms unless they are obvious</h3><a class="heading-link" href="#avoid-abbreviations-and-acronyms-unless-they-are-obvious" aria-label="Link to 'AVOID abbreviations and acronyms unless they are obvious' section">#</a></div><p>Many people don't know what "i.e.", "e.g." and "et al." mean. That acronym that you're sure everyone in your field knows may not be as widely known as you think.</p><div class="header-wrapper"><h3 id="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</h3><a class="heading-link" href="#prefer-using-this-instead-of-the-to-refer-to-a-members-instance" aria-label="Link to 'PREFER using "this" instead of "the" to refer to a member's instance' section">#</a></div><p>When documenting a member for a class, you often need to refer back to the object the member is being called on. Using "the" can be ambiguous.</p> <?code-excerpt "docs_good.dart (this)"?> <div class="code-block-wrapper language-dart"><div class="code-block-body"><span class="code-block-language" title="Language dart">dart</span><pre class="shiki dash-light" tabindex="0"><code><span class="line"><span style="color:#D43324">class</span><span style="color:#0468D7"> Box</span><span style="color:#222222"> {</span></span> <span class="line"><span style="color:#6E6E70"> /// The value this wraps.</span></span> <span class="line"><span style="color:#0468D7"> Object</span><span style="color:#222222">? _value;</span></span> <span class="line"></span> <span class="line"><span style="color:#6E6E70"> /// True if this box contains a value.</span></span> <span class="line"><span style="color:#0468D7"> bool</span><span style="color:#D43324"> get</span><span style="color:#222222"> hasValue => _value != </span><span style="color:#11796D">null</span><span style="color:#222222">;</span></span> <span class="line"><span style="color:#222222">}</span></span></code></pre></div></div><nav id="subnav"><ul><li class="previous"><a href="/effective-dart/style">&lang;  Style</a></li><li class="next"><a href="/effective-dart/usage">Usage  &rang;</a></li></ul></nav><p id="page-github-links"><span>Unless stated otherwise, the documentation on this site reflects Dart 3.5.4. Page last updated on 2024-11-17.</span> <a href="https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/documentation.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/documentation/&page-source=https://github.com/dart-lang/site-www/tree/main/src/content/effective-dart/documentation.md" title="Report an issue with this page" target="_blank" rel="noopener">report an issue</a>.</p></div></article></main><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="Medium blog"><svg><use href="/assets/img/social/medium.svg#medium"></use></svg> </a><a href="https://github.com/dart-lang" target="_blank" rel="noopener" title="GitHub"><svg><use href="/assets/img/social/github.svg#github"></use></svg> </a><a href="https://twitter.com/dart_lang" target="_blank" rel="noopener" title="X (Twitter)"><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></body></html>