Here are some guidelines for writing consistent, usable APIs for libraries.

Naming is an important part of writing readable, maintainable code. The following best practices can help you achieve that goal.

Use the same name for the same thing, throughout your code. If a precedent already exists outside your API that users are likely to know, follow that precedent.

pageCount// A field.updatePageCount()// Consistent with pageCount.toSomething()// Consistent with Iterable's toList().asSomething()// Consistent with List's asMap().Point// A familiar concept.

renumberPages()// Confusingly different from pageCount.convertToSomething()// Inconsistent with toX() precedent.wrappedAsSomething()// Inconsistent with asX() precedent.Cartesian// Unfamiliar to most users.

The goal is to take advantage of what the user already knows. This includes their knowledge of the problem domain itself, the conventions of the core libraries, and other parts of your own API. By building on top of those, you reduce the amount of new knowledge they have to acquire before they can be productive.

Unless the abbreviation is more common than the unabbreviated term, don't abbreviate. If you do abbreviate,capitalize it correctly.

pageCountbuildRectanglesIOStreamHttpRequest

numPages// "Num" is an abbreviation of "number (of)".buildRectsInputOutputStreamHypertextTransferProtocolRequest

The last word should be the most descriptive of what the thing is. You can prefix it with other words, such as adjectives, to further describe the thing.

pageCount// A count (of pages).ConversionSink// A sink for doing conversions.ChunkedConversionSink// A ConversionSink that's chunked.CssFontFaceRule// A rule for font faces in CSS.

numPages// Not a collection of pages.CanvasRenderingContext2D// Not a "2D".RuleFontFaceCss// Not a CSS.

When in doubt about naming, write some code that uses your API, and try to read it like a sentence.

// "If errors is empty..."if(errors.isEmpty){// ...}​// "Hey, subscription, cancel!"subscription.cancel();​// "Get the monsters where the monster has claws."monsters.where((monster)=>monster.hasClaws);

// Telling errors to empty itself, or asking if it is?if(errors.empty){// ...}​// Toggle what? To what?subscription.toggle();​// Filter the monsters with claws *out* or include *only* those?monsters.filter((monster)=>monster.hasClaws);

It's helpful to try out your API and see how it "reads" when used in code, but you can go too far. It's not helpful to add articles and other parts of speech to force your names toliterally read like a grammatically correct sentence.

if(theCollectionOfErrors.isEmpty){// ...}​monsters.producesANewSequenceWhereEach((monster)=>monster.hasClaws);

The reader's focus is onwhat the property is. If the user cares more abouthow a property is determined, then it should probably be a method with a verb phrase name.

list.lengthcontext.lineWidthquest.rampagingSwampBeast

list.deleteItems

Boolean names are often used as conditions in control flow, so you want a name that reads well there. Compare:

if(window.closeable)...// Adjective.if(window.canClose)...// Verb.

Good names tend to start with one of a few kinds of verbs:

• a form of "to be":isEnabled,wasShown,willFire. These are, by far, the most common.

• anauxiliary verb:hasElements,canClose,shouldConsume,mustSave.

• an active verb:ignoresInput,wroteFile. These are rare because they are usually ambiguous.loggedResult is a bad name because it could mean "whether or not a result was logged" or "the result that was logged". Likewise,closingConnection could be "whether the connection is closing" or "the connection that is closing". Active verbs are allowed when the name canonly be read as a predicate.

What separates all these verb phrases from method names is that they are notimperative. A boolean name should never sound like a command to tell the object to do something, because accessing a property doesn't change the object. (If the propertydoes modify the object in a meaningful way, it should be a method.)

isEmptyhasElementscanCloseclosesWindowcanShowPopuphasShownPopup

empty// Adjective or verb?withElements// Sounds like it might hold elements.closeable// Sounds like an interface.// "canClose" reads better as a sentence.closingWindow// Returns a bool or a window?showPopup// Sounds like it shows the popup.

This refines the previous rule. For named parameters that are boolean, the name is often just as clear without the verb, and the code reads better at the call site.

Isolate.spawn(entryPoint,message,paused:false);varcopy=List.from(elements,growable:true);varregExp=RegExp(pattern,caseSensitive:false);

Most boolean names have conceptually "positive" and "negative" forms where the former feels like the fundamental concept and the latter is its negation—"open" and "closed", "enabled" and "disabled", etc. Often the latter name literally has a prefix that negates the former: "visible" and "in-visible", "connected" and "dis-connected", "zero" and "non-zero".

When choosing which of the two cases thattrue represents—and thus which case the property is named for—prefer the positive or more fundamental one. Boolean members are often nested inside logical expressions, including negation operators. If your property itself reads like a negation, it's harder for the reader to mentally perform the double negation and understand what the code means.

if(socket.isConnected&&database.hasData){socket.write(database.read());}

if(!socket.isDisconnected&&!database.isEmpty){socket.write(database.read());}

For some properties, there is no obvious positive form. Is a document that has been flushed to disk "saved" or "un-changed"? Is a document thathasn't been flushed "un-saved" or "changed"? In ambiguous cases, lean towards the choice that is less likely to be negated by users or has the shorter name.

Exception: With some properties, the negative form is what users overwhelmingly need to use. Choosing the positive case would force them to negate the property with! everywhere. Instead, it may be better to use the negative case for that property.

Callable members can return a result to the caller and perform other work or side effects. In an imperative language like Dart, members are often called mainly for their side effect: they may change an object's internal state, produce some output, or talk to the outside world.

Those kinds of members should be named using an imperative verb phrase that clarifies the work the member performs.

list.add('element');queue.removeFirst();window.refresh();

This way, an invocation reads like a command to do that work.

Other callable members have few side effects but return a useful result to the caller. If the member needs no parameters to do that, it should generally be a getter. But sometimes a logical "property" needs some parameters. For example,elementAt() returns a piece of data from a collection, but it needs a parameter to knowwhich piece of data to return.

This means the member issyntactically a method, butconceptually it is a property, and should be named as such using a phrase that describeswhat the member returns.

varelement=list.elementAt(3);varfirst=list.firstWhere(test);varchar=string.codeUnitAt(4);

This guideline is deliberately softer than the previous one. Sometimes a method has no side effects but is still simpler to name with a verb phrase likelist.take() orstring.split().

When a member produces a result without any side effects, it should usually be a getter or a method with a noun phrase name describing the result it returns. However, sometimes the work required to produce that result is important. It may be prone to runtime failures, or use heavyweight resources like networking or file I/O. In cases like this, where you want the caller to think about the work the member is doing, give the member a verb phrase name that describes that work.

vartable=database.downloadData();varpackageVersions=packageGraph.solveConstraints();

Note, though, that this guideline is softer than the previous two. The work an operation performs is often an implementation detail that isn't relevant to the caller, and performance and robustness boundaries change over time. Most of the time, name your members based onwhat they do for the caller, nothow they do it.

In most cases, the method should be a getter withget removed from the name. For example, instead of a method namedgetBreakfastOrder(), define a getter namedbreakfastOrder.

Even if the member does need to be a method because it takes arguments or otherwise isn't a good fit for a getter, you should still avoidget. Like the previous guidelines state, either:

• Simply dropget anduse a noun phrase name likebreakfastOrder() if the caller mostly cares about the value the method returns.

• Use a verb phrase name if the caller cares about the work being done, but pick a verb that more precisely describes the work thanget, likecreate,download,fetch,calculate,request,aggregate, etc.

Linter rule:use_to_and_as_if_applicable

Aconversion method is one that returns a new object containing a copy of almost all of the state of the receiver but usually in some different form or representation. The core libraries have a convention that these methods are named starting withto followed by the kind of result.

If you define a conversion method, it's helpful to follow that convention.

list.toSet();stackTrace.toString();dateTime.toLocal();

Linter rule:use_to_and_as_if_applicable

Conversion methods are "snapshots". The resulting object has its own copy of the original object's state. There are other conversion-like methods that returnviews—they provide a new object, but that object refers back to the original. Later changes to the original object are reflected in the view.

The core library convention for you to follow isas___().

varmap=table.asMap();varlist=bytes.asFloat32List();varfuture=subscription.asFuture();

The user will see the argument at the call site, so it usually doesn't help readability to also refer to it in the name itself.

list.add(element);map.remove(key);

list.addElement(element)map.removeKey(key)

However, it can be useful to mention a parameter to disambiguate it from other similarly-named methods that take different types:

map.containsKey(key);map.containsValue(value);

Single letter names aren't exactly illuminating, but almost all generic types use them. Fortunately, they mostly use them in a consistent, mnemonic way. The conventions are:

• E for theelement type in a collection:

  gooddart

  classIterableBase<E>{}classList<E>{}classHashSet<E>{}classRedBlackTree<E>{}

  content_copy

• K andV for thekey andvalue types in an associative collection:

  gooddart

  classMap<K,V>{}classMultimap<K,V>{}classMapEntry<K,V>{}

  content_copy

• R for a type used as thereturn type of a function or a class's methods. This isn't common, but appears in typedefs sometimes and in classes that implement the visitor pattern:

  gooddart

  abstractclassExpressionVisitor<R>{RvisitBinary(BinaryExpressionnode);RvisitLiteral(LiteralExpressionnode);RvisitUnary(UnaryExpressionnode);}

  content_copy

• Otherwise, useT,S, andU for generics that have a single type parameter and where the surrounding type makes its meaning obvious. There are multiple letters here to allow nesting without shadowing a surrounding name. For example:

  gooddart

  classFuture<T>{Future<S>then<S>(FutureOr<S>onValue(Tvalue))=>...}

  content_copy

  Here, the generic methodthen<S>() usesS to avoid shadowing theT onFuture<T>.

If none of the above cases are a good fit, then either another single-letter mnemonic name or a descriptive name is fine:

classGraph<N,E>{finalList<N>nodes=[];finalList<E>edges=[];}​classGraph<Node,Edge>{finalList<Node>nodes=[];finalList<Edge>edges=[];}

In practice, the existing conventions cover most type parameters.

A leading underscore character (_ ) indicates that a member is private to its library. This is not mere convention, but is built into the language itself.

A public declaration in a library—either top level or in a class—is a signal that other libraries can and should access that member. It is also a commitment on your library's part to support that and behave properly when it happens.

If that's not what you intend, add the little_ and be happy. Narrow public interfaces are easier for you to maintain and easier for users to learn. As a nice bonus, the analyzer will tell you about unused private declarations so you can delete dead code. It can't do that if the member is public because it doesn't know if any code outside of its view is using it.

Some languages, such as Java, tie the organization of files to the organization of classes—each file may only define a single top level class. Dart does not have that limitation. Libraries are distinct entities separate from classes. It's perfectly fine for a single library to contain multiple classes, top level variables, and functions if they all logically belong together.

Placing multiple classes together in one library can enable some useful patterns. Since privacy in Dart works at the library level, not the class level, this is a way to define "friend" classes like you might in C++. Every class declared in the same library can access each other's private members, but code outside of that library cannot.

Of course, this guideline doesn't mean youshould put all of your classes into a huge monolithic library, just that you are allowed to place more than one class in a single library.

Dart is a "pure" object-oriented language in that all objects are instances of classes. But Dart does not require all code to be defined inside a class—you can define top-level variables, constants, and functions like you can in a procedural or functional language.

Linter rule:one_member_abstracts

Unlike Java, Dart has first-class functions, closures, and a nice light syntax for using them. If all you need is something like a callback, just use a function. If you're defining a class and it only has a single abstract member with a meaningless name likecall orinvoke, there is a good chance you just want a function.

typedefPredicate<E>=boolFunction(Eelement);

abstractclassPredicate<E>{booltest(Eelement);}

Linter rule:avoid_classes_with_only_static_members

In Java and C#, every definitionmust be inside a class, so it's common to see "classes" that exist only as a place to stuff static members. Other classes are used as namespaces—a way to give a shared prefix to a bunch of members to relate them to each other or avoid a name collision.

Dart has top-level functions, variables, and constants, so you don'tneed a class just to define something. If what you want is a namespace, a library is a better fit. Libraries support import prefixes and show/hide combinators. Those are powerful tools that let the consumer of your code handle name collisions in the way that works best forthem.

If a function or variable isn't logically tied to a class, put it at the top level. If you're worried about name collisions, give it a more precise name or move it to a separate library that can be imported with a prefix.

DateTimemostRecent(List<DateTime>dates){returndates.reduce((a,b)=>a.isAfter(b)?a:b);}​const_favoriteMammal='weasel';

classDateUtils{staticDateTimemostRecent(List<DateTime>dates){returndates.reduce((a,b)=>a.isAfter(b)?a:b);}}​class_Favorites{staticconstmammal='weasel';}

In idiomatic Dart, classes definekinds of objects. A type that is never instantiated is a code smell.

However, this isn't a hard rule. For example, with constants and enum-like types, it may be natural to group them in a class.

classColor{staticconstred='#f00';staticconstgreen='#0f0';staticconstblue='#00f';staticconstblack='#000';staticconstwhite='#fff';}

If a constructor is changed from a generative constructor to a factory constructor, any subclass constructor calling that constructor will break. Also, if a class changes which of its own methods it invokes onthis, that may break subclasses that override those methods and expect them to be called at certain points.

Both of these mean that a class needs to be deliberate about whether or not it wants to allow subclassing. This can be communicated in a doc comment, or by giving the class an obvious name likeIterableBase. If the author of the class doesn't do that, it's best to assume you shouldnot extend the class. Otherwise, later changes to it may break your code.

Class modifiers likefinal,interface, orsealed restrict how a class can be extended. For example, usefinal class A {} orinterface class B {} to prevent extension outside the current library. Use these modifiers to communicate your intent, rather than relying on documentation.

Implicit interfaces are a powerful tool in Dart to avoid having to repeat the contract of a class when it can be trivially inferred from the signatures of an implementation of that contract.

But implementing a class's interface is a very tight coupling to that class. It means virtuallyany change to the class whose interface you are implementing will break your implementation. For example, adding a new member to a class is usually a safe, non-breaking change. But if you are implementing that class's interface, now your class has a static error because it lacks an implementation of that new method.

Library maintainers need the ability to evolve existing classes without breaking users. If you treat every class like it exposes an interface that users are free to implement, then changing those classes becomes very difficult. That difficulty in turn means the libraries you rely on are slower to grow and adapt to new needs.

To give the authors of the classes you use more leeway, avoid implementing implicit interfaces except for classes that are clearly intended to be implemented. Otherwise, you may introduce a coupling that the author doesn't intend, and they may break your code without realizing it.

When designing a library, use class modifiers likefinal,base, orsealed to enforce intended usage. For example, usefinal class C {} orbase class D {} to prevent implementation outside the current library. While it's ideal for all libraries to use these modifiers to enforce design intent, developers may still encounter cases where they aren't applied. In such cases, be mindful of unintended implementation issues.

Linter rule:prefer_mixin

Dart previously (language version2.12 to2.19) allowed any class that met certain restrictions (no non-default constructor, no superclass, etc.) to be mixed into other classes. This was confusing because the author of the class might not have intended it to be mixed in.

Dart 3.0.0 now requires that any type intended to be mixed into other classes, as well as treated as a normal class, must be explicitly declared as such with themixin class declaration.

Types that need to be both a mixin and a class should be a rare case, however. Themixin class declaration is mostly meant to help migrate pre-3.0.0 classes being used as mixins to a more explicit declaration. New code should clearly define the behavior and intention of its declarations by using only puremixin or pureclass declarations, and avoid the ambiguity of mixin classes.

ReadMigrating classes as mixins for more guidance onmixin andmixin class declarations.

Dart constructors are created by declaring a function with the same name as the class and, optionally, an additional identifier. The latter are callednamed constructors.

If you have a class where all the fields are final, and the constructor does nothing but initialize them, you can make that constructorconst. That lets users create instances of your class in places where constants are required—inside other larger constants, switch cases, default parameter values, etc.

If you don't explicitly make itconst, they aren't able to do that.

Note, however, that aconst constructor is a commitment in your public API. If you later change the constructor to non-const, it will break users that are calling it in constant expressions. If you don't want to commit to that, don't make itconst. In practice,const constructors are most useful for simple, immutable value-like types.

A member belongs to an object and can be either methods or instance variables.

Linter rule:prefer_final_fields

State that is notmutable—that does not change over time—is easier for programmers to reason about. Classes and libraries that minimize the amount of mutable state they work with tend to be easier to maintain. Of course, it is often useful to have mutable data. But, if you don't need it, your default should be to make fields and top-level variablesfinal when you can.

Sometimes an instance field doesn't change after it has been initialized, but can't be initialized until after the instance is constructed. For example, it may need to referencethis or some other field on the instance. In cases like that, consider making the fieldlate final. When you do, you may also be able toinitialize the field at its declaration.

Deciding when a member should be a getter versus a method is a subtle but important part of good API design, hence this very long guideline. Some other language's cultures shy away from getters. They only use them when the operation is almost exactly like a field—it does a minuscule amount of calculation on state that lives entirely on the object. Anything more complex or heavyweight than that gets() after the name to signal "computation goin' on here!" because a bare name after a. means "field".

Dart isnot like that. In Dart,all dotted names are member invocations that may do computation. Fields are special—they're getters whose implementation is provided by the language. In other words, getters are not "particularly slow fields" in Dart; fields are "particularly fast getters".

Even so, choosing a getter over a method sends an important signal to the caller. The signal, roughly, is that the operation is "field-like". The operation, at least in principle,could be implemented using a field, as far as the caller knows. That implies:

• The operation does not take any arguments and returns a result.

• The caller cares mostly about the result. If you want the caller to worry abouthow the operation produces its result more than they do the result being produced, then give the operation a verb name that describes the work and make it a method.

  This doesnot mean the operation has to be particularly fast in order to be a getter.IterableBase.length isO(n), and that's OK. It's fine for a getter to do significant calculation. But if it does asurprising amount of work, you may want to draw their attention to that by making it a method whose name is a verb describing what it does.

  baddart

  connection.nextIncomingMessage;// Does network I/O.expression.normalForm;// Could be exponential to calculate.

  content_copy

• The operation does not have user-visible side effects. Accessing a real field does not alter the object or any other state in the program. It doesn't produce output, write files, etc. A getter shouldn't do those things either.

  The "user-visible" part is important. It's fine for getters to modify hidden state or produce out of band side effects. Getters can lazily calculate and store their result, write to a cache, log stuff, etc. As long as the caller doesn'tcare about the side effect, it's probably fine.

  baddart

  stdout.newline;// Produces output.list.clear;// Modifies object.

  content_copy

• The operation isidempotent. "Idempotent" is an odd word that, in this context, basically means that calling the operation multiple times produces the same result each time, unless some state is explicitly modified between those calls. (Obviously,list.length produces different results if you add an element to the list between calls.)

  "Same result" here does not mean a getter must literally produce an identical object on successive calls. Requiring that would force many getters to have brittle caching, which negates the whole point of using a getter. It's common, and perfectly fine, for a getter to return a new future or list each time you call it. The important part is that the future completes to the same value, and the list contains the same elements.

  In other words, the result value should be the samein the aspects that the caller cares about.

  baddart

  DateTime.now;// New result each time.

  content_copy

• The resulting object doesn't expose all of the original object's state. A field exposes only a piece of an object. If your operation returns a result that exposes the original object's entire state, it's likely better off as ato___() oras___() method.

If all of the above describe your operation, it should be a getter. It seems like few members would survive that gauntlet, but surprisingly many do. Many operations just do some computation on some state and most of those can and should be getters.

rectangle.area;collection.isEmpty;button.canShow;dataSet.minimumValue;

Linter rule:use_setters_to_change_properties

Deciding between a setter versus a method is similar to deciding between a getter versus a method. In both cases, the operation should be "field-like".

For a setter, "field-like" means:

• The operation takes a single argument and does not produce a result value.

• The operation changes some state in the object.

• The operation is idempotent. Calling the same setter twice with the same value should do nothing the second time as far as the caller is concerned. Internally, maybe you've got some cache invalidation or logging going on. That's fine. But from the caller's perspective, it appears that the second call does nothing.

rectangle.width=3;button.visible=false;

Linter rule:avoid_setters_without_getters

Users think of getters and setters as visible properties of an object. A "dropbox" property that can be written to but not seen is confusing and confounds their intuition about how properties work. For example, a setter without a getter means you can use= to modify it, but not+=.

This guideline doesnot mean you should add a getter just to permit the setter you want to add. Objects shouldn't generally expose more state than they need to. If you have some piece of an object's state that can be modified but not exposed in the same way, use a method instead.

It's common for an API to support similar operations on different types of parameters. To emphasize the similarity, some languages supportoverloading, which lets you define multiple methods that have the same name but different parameter lists. At compile time, the compiler looks at the actual argument types to determine which method to call.

Dart doesn't have overloading. You can define an API that looks like overloading by defining a single method and then usingis type tests inside the body to look at the runtime types of the arguments and perform the appropriate behavior. However, faking overloading this way turns acompile time method selection into a choice that happens atruntime.

If callers usually know which type they have and which specific operation they want, it's better to define separate methods with different names to let callers select the right operation. This gives better static type checking and faster performance since it avoids any runtime type tests.

However, if users might have an object of an unknown type andwant the API to internally useis to pick the right operation, then a single method where the parameter is a supertype of all of the supported types might be reasonable.

Unlike otherfinal fields, alate final field without an initializerdoes define a setter. If that field is public, then the setter is public. This is rarely what you want. Fields are usually markedlate so that they can be initializedinternally at some point in the instance's lifetime, often inside the constructor body.

Unless youdo want users to call the setter, it's better to pick one of the following solutions:

• Don't uselate.
• Use a factory constructor to compute thefinal field values.
• Uselate, but initialize thelate field at its declaration.
• Uselate, but make thelate field private and define a public getter for it.

When an API returns a container type, it has two ways to indicate the absence of data: It can return an empty container or it can returnnull. Users generally assume and prefer that you use an empty container to indicate "no data". That way, they have a real object that they can call methods on likeisEmpty.

To indicate that your API has no data to provide, prefer returning an empty collection, a non-nullable future of a nullable type, or a stream that doesn't emit any values.

Exception: If returningnullmeans something different from yielding an empty container, it might make sense to use a nullable type.

Linter rule:avoid_returning_this

Method cascades are a better solution for chaining method calls.

varbuffer=StringBuffer()..write('one')..write('two')..write('three');

varbuffer=StringBuffer().write('one').write('two').write('three');

When you write down a type in your program, you constrain the kinds of values that flow into different parts of your code. Types can appear in two kinds of places:type annotations on declarations and type arguments togeneric invocations.

Type annotations are what you normally think of when you think of "static types". You can type annotate a variable, parameter, field, or return type. In the following example,bool andString are type annotations. They hang off the static declarative structure of the code and aren't "executed" at runtime.

boolisEmpty(Stringparameter){boolresult=parameter.isEmpty;returnresult;}

A generic invocation is a collection literal, a call to a generic class's constructor, or an invocation of a generic method. In the next example,num andint are type arguments on generic invocations. Even though they are types, they are first-class entities that get reified and passed to the invocation at runtime.

varlists=<num>[1,2];lists.addAll(List<num>.filled(3,4));lists.cast<int>();

We stress the "generic invocation" part here, because type arguments canalso appear in type annotations:

List<int>ints=[1,2];

Here,int is a type argument, but it appears inside a type annotation, not a generic invocation. You usually don't need to worry about this distinction, but in a couple of places, we have different guidance for when a type is used in a generic invocation as opposed to a type annotation.

Type annotations are optional in Dart. If you omit one, Dart tries to infer a type based on the nearby context. Sometimes it doesn't have enough information to infer a complete type. When that happens, Dart sometimes reports an error, but usually silently fills in any missing parts withdynamic. The implicitdynamic leads to code thatlooks inferred and safe, but actually disables type checking completely. The rules below avoid that by requiring types when inference fails.

The fact that Dart has both type inference and adynamic type leads to some confusion about what it means to say code is "untyped". Does that mean the code is dynamically typed, or that you didn'twrite the type? To avoid that confusion, we avoid saying "untyped" and instead use the following terminology:

• If the code istype annotated, the type was explicitly written in the code.

• If the code isinferred, no type annotation was written, and Dart successfully figured out the type on its own. Inference can fail, in which case the guidelines don't consider that inferred.

• If the code isdynamic, then its static type is the specialdynamic type. Code can be explicitly annotateddynamic or it can be inferred.

In other words, whether some code is annotated or inferred is orthogonal to whether it isdynamic or some other type.

Inference is a powerful tool to spare you the effort of writing and reading types that are obvious or uninteresting. It keeps the reader's attention focused on the behavior of the code itself. Explicit types are also a key part of robust, maintainable code. They define the static shape of an API and create boundaries to document and enforce what kinds of values are allowed to reach different parts of the program.

Of course, inference isn't magic. Sometimes inference succeeds and selects a type, but it's not the type you want. The common case is inferring an overly precise type from a variable's initializer when you intend to assign values of other types to the variable later. In those cases, you have to write the type explicitly.

The guidelines here strike the best balance we've found between brevity and control, flexibility and safety. There are specific guidelines to cover all the various cases, but the rough summary is:

• Do annotate when inference doesn't have enough context, even whendynamic is the type you want.

• Don't annotate locals and generic invocations unless you need to.

• Prefer annotating top-level variables and fields unless the initializer makes the type obvious.

Linter rule:prefer_typing_uninitialized_variables

The type of a variable—top-level, local, static field, or instance field—can often be inferred from its initializer. However, if there is no initializer, inference fails.

List<AstNode>parameters;if(nodeisConstructor){parameters=node.signature;}elseif(nodeisMethod){parameters=node.parameters;}

varparameters;if(nodeisConstructor){parameters=node.signature;}elseif(nodeisMethod){parameters=node.parameters;}

Linter rule:type_annotate_public_apis

Type annotations are important documentation for how a library should be used. They form boundaries between regions of a program to isolate the source of a type error. Consider:

install(id,destination)=>...

Here, it's unclear whatid is. A string? And what isdestination? A string or aFile object? Is this method synchronous or asynchronous? This is clearer:

Future<bool>install(PackageIdid,Stringdestination)=>...

In some cases, though, the type is so obvious that writing it is pointless:

constscreenWidth=640;// Inferred as int.

"Obvious" isn't precisely defined, but these are all good candidates:

• Literals.
• Constructor invocations.
• References to other constants that are explicitly typed.
• Simple expressions on numbers and strings.
• Factory methods likeint.parse(),Future.wait(), etc. that readers are expected to be familiar with.

If you think the initializer expression—whatever it is—is sufficiently clear, then you may omit the annotation. But if you think annotating helps make the code clearer, then add one.

When in doubt, add a type annotation. Even when a type is obvious, you may still wish to explicitly annotate. If the inferred type relies on values or declarations from other libraries, you may want to type annotateyour declaration so that a change to that other library doesn't silently change the type of your own API without you realizing.

This rule applies to both public and private declarations. Just as type annotations on APIs helpusers of your code, types on private members helpmaintainers.

Linter rule:omit_local_variable_types

Local variables, especially in modern code where functions tend to be small, have very little scope. Omitting the type focuses the reader's attention on the more importantname of the variable and its initialized value.

List<List<Ingredient>>possibleDesserts(Set<Ingredient>pantry){vardesserts=<List<Ingredient>>[];for(finalrecipeincookbook){if(pantry.containsAll(recipe)){desserts.add(recipe);}}​returndesserts;}

List<List<Ingredient>>possibleDesserts(Set<Ingredient>pantry){List<List<Ingredient>>desserts=<List<Ingredient>>[];for(finalList<Ingredient>recipeincookbook){if(pantry.containsAll(recipe)){desserts.add(recipe);}}​returndesserts;}

Sometimes the inferred type is not the type you want the variable to have. For example, you may intend to assign values of other types later. In that case, annotate the variable with the type you want.

Widgetbuild(BuildContextcontext){Widgetresult=Text('You won!');if(applyPadding){result=Padding(padding:EdgeInsets.all(8.0),child:result);}returnresult;}

Dart doesn't generally infer the return type of a function declaration from its body, unlike some other languages. That means you should write a type annotation for the return type yourself.

StringmakeGreeting(Stringwho){return'Hello,$who!';}

makeGreeting(Stringwho){return'Hello,$who!';}

Note that this guideline only applies tonon-local function declarations: top-level, static, and instance methods and getters. Local functions and anonymous function expressions infer a return type from their body. In fact, the anonymous function syntax doesn't even allow a return type annotation.

A function's parameter list determines its boundary to the outside world. Annotating parameter types makes that boundary well defined. Note that even though default parameter values look like variable initializers, Dart doesn't infer an optional parameter's type from its default value.

voidsayRepeatedly(Stringmessage,{intcount=2}){for(vari=0;i<count;i++){print(message);}}

voidsayRepeatedly(message,{count=2}){for(vari=0;i<count;i++){print(message);}}

Exception: Function expressions and initializing formals have different type annotation conventions, as described in the next two guidelines.

Linter rule:avoid_types_on_closure_parameters

Anonymous functions are almost always immediately passed to a method taking a callback of some type. When a function expression is created in a typed context, Dart tries to infer the function's parameter types based on the expected type. For example, when you pass a function expression toIterable.map(), your function's parameter type is inferred based on the type of callback thatmap() expects:

varnames=people.map((person)=>person.name);

varnames=people.map((Personperson)=>person.name);

If the language is able to infer the type you want for a parameter in a function expression, then don't annotate. In rare cases, the surrounding context isn't precise enough to provide a type for one or more of the function's parameters. In those cases, you may need to annotate. (If the function isn't used immediately, it's usually better tomake it a named declaration.)

Linter rule:type_init_formals

If a constructor parameter is usingthis. to initialize a field, orsuper. to forward a super parameter, then the type of the parameter is inferred to have the same type as the field or super-constructor parameter respectively.

classPoint{doublex,y;Point(this.x,this.y);}​classMyWidgetextendsStatelessWidget{MyWidget({super.key});}

classPoint{doublex,y;Point(doublethis.x,doublethis.y);}​classMyWidgetextendsStatelessWidget{MyWidget({Key?super.key});}

Dart is pretty smart about inferring type arguments in generic invocations. It looks at the expected type where the expression occurs and the types of values being passed to the invocation. However, sometimes those aren't enough to fully determine a type argument. In that case, write the entire type argument list explicitly.

varplayerScores=<String,int>{};finalevents=StreamController<Event>();

varplayerScores={};finalevents=StreamController();

Sometimes the invocation occurs as the initializer to a variable declaration. If the variable isnot local, then instead of writing the type argument list on the invocation itself, you may put a type annotation on the declaration:

classDownloader{finalCompleter<String>response=Completer();}

classDownloader{finalresponse=Completer();}

Annotating the variable also addresses this guideline because now the type argumentsare inferred.

This is the converse of the previous rule. If an invocation's type argument listis correctly inferred with the types you want, then omit the types and let Dart do the work for you.

classDownloader{finalCompleter<String>response=Completer();}

classDownloader{finalCompleter<String>response=Completer<String>();}

Here, the type annotation on the field provides a surrounding context to infer the type argument of constructor call in the initializer.

varitems=Future.value([1,2,3]);

varitems=Future<List<int>>.value(<int>[1,2,3]);

Here, the types of the collection and instance can be inferred bottom-up from their elements and arguments.

The goal of writing a type annotation or type argument is to pin down a complete type. However, if you write the name of a generic type but omit its type arguments, you haven't fully specified the type. In Java, these are called "raw types". For example:

Listnumbers=[1,2,3];varcompleter=Completer<Map>();

Here,numbers has a type annotation, but the annotation doesn't provide a type argument to the genericList. Likewise, theMap type argument toCompleter isn't fully specified. In cases like this, Dart willnot try to "fill in" the rest of the type for you using the surrounding context. Instead, it silently fills in any missing type arguments withdynamic (or the bound if the class has one). That's rarely what you want.

Instead, if you're writing a generic type either in a type annotation or as a type argument inside some invocation, make sure to write a complete type:

List<num>numbers=[1,2,3];varcompleter=Completer<Map<String,int>>();

When inference doesn't fill in a type, it usually defaults todynamic. Ifdynamic is the type you want, this is technically the most terse way to get it. However, it's not the mostclear way. A casual reader of your code who sees that an annotation is missing has no way of knowing if you intended it to bedynamic, expected inference to fill in some other type, or simply forgot to write the annotation.

Whendynamic is the type you want, write that explicitly to make your intent clear and highlight that this code has less static safety.

dynamicmergeJson(dynamicoriginal,dynamicchanges)=>...

mergeJson(original,changes)=>...

Note that it's OK to omit the type when Dartsuccessfully infersdynamic.

Map<String,dynamic>readJson()=>...​voidprintUsers(){varjson=readJson();varusers=json['users'];print(users);}

Here, Dart infersMap<String, dynamic> forjson and then from that infersdynamic forusers. It's fine to leaveusers without a type annotation. The distinction is a little subtle. It's OK to allow inference topropagatedynamic through your code from adynamic type annotation somewhere else, but you don't want it to inject adynamic type annotation in a place where your code did not specify one.

The identifierFunction by itself without any return type or parameter signature refers to the specialFunction type. This type is only marginally more useful than usingdynamic. If you're going to annotate, prefer a full function type that includes the parameters and return type of the function.

boolisValid(Stringvalue,boolFunction(String)test)=>...

boolisValid(Stringvalue,Functiontest)=>...

Exception: Sometimes, you want a type that represents the union of multiple different function types. For example, you may accept a function that takes one parameter or a function that takes two. Since we don't have union types, there's no way to precisely type that and you'd normally have to usedynamic.Function is at least a little more helpful than that:

voidhandleError(voidFunction()operation,FunctionerrorHandler){try{operation();}catch(err,stack){if(errorHandlerisFunction(Object)){errorHandler(err);}elseif(errorHandlerisFunction(Object,StackTrace)){errorHandler(err,stack);}else{throwArgumentError('errorHandler has wrong signature.');}}}

Linter rule:avoid_return_types_on_setters

Setters always returnvoid in Dart. Writing the word is pointless.

voidsetfoo(Foovalue){...}

setfoo(Foovalue){...}

Linter rule:prefer_generic_function_type_aliases

Dart has two notations for defining a named typedef for a function type. The original syntax looks like:

typedefintComparison<T>(Ta,Tb);

That syntax has a couple of problems:

• There is no way to assign a name to ageneric function type. In the above example, the typedef itself is generic. If you referenceComparison in your code, without a type argument, you implicitly get the function typeint Function(dynamic, dynamic),notint Function<T>(T, T). This doesn't come up in practice often, but it matters in certain corner cases.

• A single identifier in a parameter is interpreted as the parameter'sname, not itstype. Given:

  baddart

  typedefboolTestNumber(num);

  content_copy

  Most users expect this to be a function type that takes anum and returnsbool. It is actually a function type that takesany object (dynamic) and returnsbool. The parameter'sname (which isn't used for anything except documentation in the typedef) is "num". This has been a long-standing source of errors in Dart.

The new syntax looks like this:

typedefComparison<T>=intFunction(T,T);

If you want to include a parameter's name, you can do that too:

typedefComparison<T>=intFunction(Ta,Tb);

The new syntax can express anything the old syntax could express and more, and lacks the error-prone misfeature where a single identifier is treated as the parameter's name instead of its type. The same function type syntax after the= in the typedef is also allowed anywhere a type annotation may appear, giving us a single consistent way to write function types anywhere in a program.

The old typedef syntax is still supported to avoid breaking existing code, but it's deprecated.

Linter rule:avoid_private_typedef_functions

In Dart, if you want to use a function type for a field, variable, or generic type argument, you can define a typedef for the function type. However, Dart supports an inline function type syntax that can be used anywhere a type annotation is allowed:

classFilteredObservable{finalboolFunction(Event)_predicate;finalList<voidFunction(Event)>_observers;​FilteredObservable(this._predicate,this._observers);​voidFunction(Event)?notify(Eventevent){if(!_predicate(event))returnnull;​voidFunction(Event)?last;for(finalobserverin_observers){observer(event);last=observer;}​returnlast;}}

It may still be worth defining a typedef if the function type is particularly long or frequently used. But in most cases, users want to see what the function type actually is right where it's used, and the function type syntax gives them that clarity.

Linter rule:use_function_type_syntax_for_parameters

Dart has a special syntax when defining a parameter whose type is a function. Sort of like in C, you surround the parameter's name with the function's return type and parameter signature:

Iterable<T>where(boolpredicate(Telement))=>...

Before Dart added function type syntax, this was the only way to give a parameter a function type without defining a typedef. Now that Dart has a general notation for function types, you can use it for function-typed parameters as well:

Iterable<T>where(boolFunction(T)predicate)=>...

The new syntax is a little more verbose, but is consistent with other locations where you must use the new syntax.

Some operations work with any possible object. For example, alog() method could take any object and calltoString() on it. Two types in Dart permit all values:Object? anddynamic. However, they convey different things. If you simply want to state that you allow all objects, useObject?. If you want to allow all objectsexceptnull, then useObject.

The typedynamic not only accepts all objects, but it also permits alloperations. Any member access on a value of typedynamic is allowed at compile time, but may fail and throw an exception at runtime. If you want exactly that risky but flexible dynamic dispatch, thendynamic is the right type to use.

Otherwise, prefer usingObject? orObject. Rely onis checks and type promotion to ensure that the value's runtime type supports the member you want to access before you access it.

/// Returns a Boolean representation for [arg], which must/// be a String or bool.boolconvertToBool(Objectarg){if(argisbool)returnarg;if(argisString)returnarg.toLowerCase()=='true';throwArgumentError('Cannot convert$arg to a bool.');}

The main exception to this rule is when working with existing APIs that usedynamic, especially inside a generic type. For example, JSON objects have typeMap<String, dynamic> and your code will need to accept that same type. Even so, when using a value from one of these APIs, it's often a good idea to cast it to a more precise type before accessing members.

When you have a synchronous function that doesn't return a value, you usevoid as the return type. The asynchronous equivalent for a method that doesn't produce a value, but that the caller might need to await, isFuture<void>.

You may see code that usesFuture orFuture<Null> instead because older versions of Dart didn't allowvoid as a type argument. Now that it does, you should use it. Doing so more directly matches how you'd type a similar synchronous function, and gives you better error-checking for callers and in the body of the function.

For asynchronous functions that do not return a useful value and where no callers need to await the asynchronous work or handle an asynchronous failure, use a return type ofvoid.

If a method accepts aFutureOr<int>, it isgenerous in what it accepts. Users can call the method with either anint or aFuture<int>, so they don't need to wrap anint inFuture that you are going to unwrap anyway.

If youreturn aFutureOr<int>, users need to check whether get back anint or aFuture<int> before they can do anything useful. (Or they'll justawait the value, effectively always treating it as aFuture.) Just return aFuture<int>, it's cleaner. It's easier for users to understand that a function is either always asynchronous or always synchronous, but a function that can be either is hard to use correctly.

Future<int>triple(FutureOr<int>value)async=>(awaitvalue)*3;

FutureOr<int>triple(FutureOr<int>value){if(valueisint)returnvalue*3;returnvalue.then((v)=>v*3);}

The more precise formulation of this guideline is toonly useFutureOr<T> incontravariant positions. Parameters are contravariant and return types are covariant. In nested function types, this gets flipped—if you have a parameter whose type is itself a function, then the callback's return type is now in contravariant position and the callback's parameters are covariant. This means it's OK for acallback's type to returnFutureOr<T>:

Stream<S>asyncMap<T,S>(Iterable<T>iterable,FutureOr<S>Function(T)callback,)async*{for(finalelementiniterable){yieldawaitcallback(element);}}

In Dart, optional parameters can be either positional or named, but not both.

Linter rule:avoid_positional_boolean_parameters

Unlike other types, booleans are usually used in literal form. Values like numbers are usually wrapped in named constants, but we typically pass aroundtrue andfalse directly. That can make call sites unreadable if it isn't clear what the boolean represents:

newTask(true);newTask(false);newListBox(false,true,true);newButton(false);

Instead, prefer using named arguments, named constructors, or named constants to clarify what the call is doing.

Task.oneShot();Task.repeating();ListBox(scroll:true,showScrollbars:true);Button(ButtonState.enabled);

Note that this doesn't apply to setters, where the name makes it clear what the value represents:

listBox.canScroll=true;button.isEnabled=false;

Optional positional parameters should have a logical progression such that earlier parameters are passed more often than later ones. Users should almost never need to explicitly pass a "hole" to omit an earlier positional argument to pass later one. You're better off using named arguments for that.

String.fromCharCodes(Iterable<int>charCodes,[intstart=0,int?end]);​DateTime(intyear,[intmonth=1,intday=1,inthour=0,intminute=0,intsecond=0,intmillisecond=0,intmicrosecond=0,]);​Duration({intdays=0,inthours=0,intminutes=0,intseconds=0,intmilliseconds=0,intmicroseconds=0,});

If the user is logically omitting a parameter, prefer letting them actually omit it by making the parameter optional instead of forcing them to passnull, an empty string, or some other special value that means "did not pass".

Omitting the parameter is more terse and helps prevent bugs where a sentinel value likenull is accidentally passed when the user thought they were providing a real value.

varrest=string.substring(start);

varrest=string.substring(start,null);

If you are defining a method or function that lets a user select a range of elements or items from some integer-indexed sequence, take a start index, which refers to the first item and a (likely optional) end index which is one greater than the index of the last item.

This is consistent with core libraries that do the same thing.

[0,1,2,3].sublist(1,3)// [1, 2]'abcd'.substring(1,3)// 'bc'

It's particularly important to be consistent here because these parameters are usually unnamed. If your API takes a length instead of an end point, the difference won't be visible at all at the call site.

Implementing custom equality behavior for a class can be tricky. Users have deep intuition about how equality works that your objects need to match, and collection types like hash tables have subtle contracts that they expect elements to follow.

Linter rule:hash_and_equals

The default hash code implementation provides anidentity hash—two objects generally only have the same hash code if they are the exact same object. Likewise, the default behavior for== is identity.

If you are overriding==, it implies you may have different objects that are considered "equal" by your class.Any two objects that are equal must have the same hash code. Otherwise, maps and other hash-based collections will fail to recognize that the two objects are equivalent.

An equivalence relation should be:

• Reflexive:a == a should always returntrue.

• Symmetric:a == b should return the same thing asb == a.

• Transitive: Ifa == b andb == c both returntrue, thena == c should too.

Users and code that uses== expect all of these laws to be followed. If your class can't obey these rules, then== isn't the right name for the operation you're trying to express.

Linter rule:avoid_equals_and_hash_code_on_mutable_classes

When you define==, you also have to definehashCode. Both of those should take into account the object's fields. If those fieldschange then that implies the object's hash code can change.

Most hash-based collections don't anticipate that—they assume an object's hash code will be the same forever and may behave unpredictably if that isn't true.

Linter rule:avoid_null_checks_in_equality_operators

The language specifies thatnull is equal only to itself, and that the== method is called only if the right-hand side is notnull.

classPerson{finalStringname;​// ···​booloperator==(Objectother)=>otherisPerson&&name==other.name;}

classPerson{finalStringname;​// ···​booloperator==(Object?other)=>other!=null&&otherisPerson&&name==other.name;}