Effective Dart

Over the past several years, we’ve written a ton of Dart code and learned a lotabout what works well and what doesn’t. We’re sharing this with you so you canwrite consistent, robust, fast code too. There are two overarching themes:

  • Be consistent. 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 consistent is objectively helpful.

If two pieces of code look different it should be because they _are_different in some meaningful way. When a bit of code stands out and catchesyour eye, it should do so for a useful reason.

  • Be brief. Dart was designed to be familiar, so it inherits many of thesame 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 thoselanguages offer. We added a bunch of features, from string interpolation toinitializing formals, to help you express your intent more simply andeasily.

If there are multiple ways to say something, you should generally pick themost concise one. This is not to say you should code golf yourself intocramming a whole program into a single line. The goal is code that iseconomical, not dense.

The Dart analyzer has a linter to help you write good, consistent code.If a linter rule exists that can help you follow a guideline,then the guideline links to that rule. Here’s an example:

Linter rule: prefer_collection_literals

For help onenabling linter rules,see the documentation forcustomizing static analysis.

The guides

We split the guidelines into a few separate pages for easy digestion:

  • Style Guide – This defines the rules for laying out andorganizing code, or at least the parts that dartfmt doesn’t handle foryou. The style guide also specifies how identifiers are formatted:camelCase, using_underscores, etc.

  • Documentation Guide – This tells you everything you need toknow about what goes inside comments. Both doc comments and regular,run-of-the-mill code comments.

  • Usage Guide – This teaches you how to make the best use oflanguage features to implement behavior. If it’s in a statement orexpression, it’s covered here.

  • Design Guide – This is the softest guide, but the onewith the widest scope. It covers what we’ve learned about designingconsistent, usable APIs for libraries. If it’s in a type signature ordeclaration, this goes over it.

For links to all the guidelines, see thesummary.

How to read the guides

Each guide is broken into a few sections. Sections contain a list of guidelines.Each guideline starts with one of these words:

  • DO guidelines describe practices that should always be followed. Therewill almost never be a valid reason to stray from them.

  • DON’T guidelines are the converse: things that are almost never a goodidea. Hopefully, we don’t have as many of these as other languages do becausewe have less historical baggage.

  • PREFER guidelines are practices that you should follow. However, theremay be circumstances where it makes sense to do otherwise. Just make sure youunderstand the full implications of ignoring the guideline when you do.

  • AVOID guidelines are the dual to “prefer”: stuff you shouldn’t do butwhere there may be good reasons to on rare occasions.

  • CONSIDER guidelines are practices that you might or might not want tofollow, depending on circumstances, precedents, and your own preference.

Some guidelines describe an exception where the rule does not apply. Whenlisted, the exceptions may not be exhaustive—you might still need to useyour judgement on other cases.

This sounds like the police are going to beat down your door if you don’t haveyour laces tied correctly. Things aren’t that bad. Most of the guidelines hereare common sense and we’re all reasonable people. The goal, as always, is nice,readable and maintainable code.

Glossary

To keep the guidelines brief, we use a few shorthand terms to refer to differentDart constructs.

  • A library member is a top-level field, getter, setter, or function.Basically, anything at the top level that isn’t a type.

  • A class member is a constructor, field, getter, setter, function, oroperator declared inside a class. Class members can be instance or static,abstract or concrete.

  • A member is either a library member or a class member.

  • A variable, when used generally, refers to top-level variables,parameters, and local variables. It doesn’t include static or instance fields.

  • A type is any named type declaration: a class, typedef, or enum.

  • A property is a top-level variable, getter (inside a class or at the toplevel, instance or static), setter (same), or field (instance or static).Roughly any “field-like” named construct.

Summary of all rules

Style

Identifiers

Ordering

Formatting

Documentation

Comments

Doc comments

Markdown

Writing

Usage

Libraries

Booleans

Strings

Collections

Functions

Parameters

Variables

Members

Constructors

Error handling

Asynchrony

Design

Names

Libraries

Classes and mixins

Constructors

Members

Types

Parameters

Equality