No Comment: All About Comments

I want to start with our discussion by talking about comments in Dart because I feel like commenting, in general, is something that not enough developers do and do effectively. Comments are a critical part of programming whether it’s something you enjoy doing or not, and as such, Dart provides three forms of comments.

Now, don’t get me wrong: I’m not suggesting this is an example of good or proper commenting! Quite the opposite in fact! I’m just using it as an example to show this form of a comment in Dart.

Anything between those two sequences is ignored.

Here, when documentation is generated (which you can do with the Dart SDK’s dartdoc tool) the [Treats] text will become a link to the API documentation for the Treats class (assuming dartdoc can find Treats in the lexical scope of the Pet class).

Nothing Stays the Same: Variables

To begin with, everything is an object in Dart. Variables in Dart, as in virtually any language, store a value or a reference to something. In some languages, there is a difference between primitives like numbers and string and objects, which are instances of classes. Not so in Dart! Everything here is an object, even simple numbers, functions, and even null are all objects, which are always instances of classes, and all of which extend from a common Object class.

Everybody Has a Type: Data Types

Dart is a strongly typed language, but curiously, you don’t need to annotate types. They’re optional, and that’s because Dart performs type inference when annotations aren’t present.

When a Single Value Just Won’t Do: Enumerations

Every value in the enum has an implicit index getter method, so you can always find the index of a given value (and you’ll get a compile error if the value isn’t valid in the enum. You can also get a list of all the values in the enum through the values property (which too also has an implicit getter). Finally, enum’s are especially useful in switch statements, and Dart will give you a compile error if you don’t have a case for all the values in the enum.

What’s Your Type: The “as” and “is” Keywords

This will only print() (which writes content to the console) the circumference if the object reference by shape is of type Circle.

That way, if shape is a Circle, it works as expected, and if shape can be cast to a Circle, then I would work too (perhaps shape is of type Oval, which is a subclass of Circle, for example).

Note, however, that in the example of is, nothing will happen if shape isn’t a Circle, but in the as example, an exception will be thrown if shape can’t be cast to Circle.

Going with the Flow: Flow Control (and Logic!) Constructs

Dart has several logic and flow control statements and constructs, most of which will be familiar to someone with any programming experience at all.

The Big Nothing: void

In most languages, if a function doesn’t return anything, you have to slap void in front of it. In Dart, which supports the void keyword , you can do that, but you don’t have to.

In Dart though, void is a bit more... curious.

First, if a function doesn’t explicitly return anything, then you can omit a return type entirely; you don’t even need to put void in front of it like most languages (although you are free to do so if you prefer). In such cases, an implicit return null; is added to the end of the function. This is the case for all the code samples thus far.

If you do put void in front of a function though, you will then get a compile-time error if you try to return anything. That makes sense. But if you try and return null, that’s okay, no error. You can also return a void function (a function that has void before it).

Given that sayHi() is a void function, you’d expect that return a from it would produce an error, right? Well, not so! It will compile. Well, it would compile, except for the print(b); line. That will cause a compile-time error, and the reason is that Dart won’t let you use anything returned from a void function (even though you can capture it, since the var b = mc.sayHi(); line compiles and executes without issue – Dart is kind of a tease that way!).

So yeah, void is kind of a weird thing in Dart. My advice is to not use it unless you specifically know that you need to.

Why you might do this is something I’ll touch upon on the section on asynchronous code.

Smooth Operators

A note on the == operator: This is a value check, not an object check. When you need to test if two variables reference the exact same object, use the identical() global function.

When using the == operator, as in if (a == b), true is returned if they are both null, false if only one is. When this expression is executed, the ==() method of the first operand (yes, == is indeed the name of a method!) is executed.

A note on the = operator: There is also a ??= operator which does the assignment only if the operand is null.

A note on the . operator: There is also a conditional version written ?. that allows you to access a member of something where that something could be null.

If person could be null , then writing print(person?.age) will avoid a null pointer error. The result, in this case, would be null printed, but no error, which is the key point.

Use whichever style is more pleasing to your eyes, Dart doesn’t care either way.

Classes can also define custom operators , but that statement doesn’t have much value unless we first talk about what classes are all about, so let’s do that now, shall we?

Classing the Joint Up: Object Orientation in Dart

Yep, that’s it!

Getting Funky with Functions

In Dart, functions are first-class citizens and have their own type: Function. What that means is that functions can be assigned to variables, can be passed as parameters, and can also be stand-alone entities. There’s one key stand-alone function you’re already aware of, and that’s main().

Here, you can see most of that at work. First, we have a stand-alone greet() function . Then, we have a class with a greetAgain() method . This method accepts a named parameter list, and look, one of those parameters is a Function! Also, see how the n parameter has a default value of human defined? Cool, right? Then, inside the function, we call the function referenced by f, passing it n. In other words, whatever function is passed in as the value of the f parameter, because it’s annotated as a Function, we can use that f reference to call it.

Now, in the main() function , we first just call greet(), passing it the name that was passed into it, to have the computer say hello. Then, we call that greetAgain() method of the MyClass instance mc, and this time, we’re passing named parameters, and the value of the f parameter is a reference to the greet() function. I show this twice so you can see how it works if you don’t pass a name, and it’ll just greet a generic human.

Unfortunately, DartPad does not, as of this writing, allow for importing libraries, which we would need to use the @required annotation that ideally would be before the n parameter in greetAgain(), but not the f parameter. So, because you may want to plug this code in to DartPad and try it, I left that annotation out. Also note that when using positional parameters, you don’t use @required, you instead wrap the optional parameters in square brackets.

Here, there’s a function passed to the forEach() method of the List object bands, but it has no name and as a result, it only exists for the lifetime of the execution of forEach().

The nestedFunction() can use any variable all the way up to the top level.

Dart also supports the concept of closures with functions so that a function will capture, or “close around,” its lexical scope, even if the function is used outside of its original scope. In other words, if a function has access to a variable, then the function will, in a sense, “remember” that variable even if the scope the variable is in is no longer “alive”, so to speak, when the function executes.

Here, the call to jenny() print 8675309, even though it wasn’t passed to it. This happens because jenny() includes the lexical scope of remember(), and the execution context at the time the reference is captured, which includes the value passed into the call to remember() when getting the reference. It’s confusing if you’ve never encountered it before, I know, but the good news is that you probably won’t need to use closures very much in Dart in my experience (as compared to, say JavaScript, where it comes up all the time).

Tell Me Is It So: Assertions

Out of Time: Asynchrony

Asychronous (or just async) programming is big business these days! It’s everywhere, in all languages, and Dart is no exception. In Dart, two classes are key to asynchrony, Future and Stream, along with two keywords, async and await. Both classes are objects that async functions return when a long-running operation begins, but before it completes, allowing the program to await the result while continuing to do other things, then continue where it left off when the result comes back.

You can await a function, whether the same or others, as many times as you wish in a single async function and execution will pause on each.

The difference between the two is simply that using a Future means that the return from the long-running function won’t occur until that function completes, however long it takes. With a Stream, the function can return data little by little over time, and your code that is awaiting it will execute any time the Stream emits a value. You can break or return from the loop to stop reading form the Stream, and the loop will end when the async function closes the Stream. As before, an await for loop is only allowed inside of an async function.

Ssshhh, Be Quiet: Libraries (and Visibility)

Libraries are used in Dart to make code modular and shareable. A library provides some external API to other code that uses it. It also serves as a method of isolation in that any identifier in a library that starts with an underscore character is visible only inside that library. Interestingly, every single Dart app is automatically a library whether you do anything special or not! Libraries can be packaged up and delivered to others using the Dart SDK’s pub tool, which is the package and asset manager

Some libraries are provided by your own code, and others are built into Dart, as is this one. For those built-in libraries, the form of the URI, which is what the part of the statement in quotes is, has a particular form: it begins with dart:, which is the scheme identifier portion of the URI.

Here, only the Account class from lib1 would be imported, and everything except the Account class from lib2 would be imported.

As you learned in the last section, that code must be in a function marked async.

Note that invoking loadLibrary() on a library multiple times is fine, no harm is done. Also, until the library is loaded, the constants defined in the library, if any, aren’t actually constants – they don’t exist until it’s loaded, so you can’t use them.

Deferred loading can also be handy if you want to do A/B testing with your app because you can dynamically load one library vs. another to test the differences.

Let’s Be Exceptional: Exception Handling

Exception handling in Dart is simple and looks a lot like Java or JavaScript, or indeed most other languages that deals with exceptions. In contrast to many other languages though, in Dart, you are not required to declare what exceptions a given function must throw, nor must you catch any. In other words, all exceptions in Dart are unchecked.

Exceptions are objects, so you need to construct one to throw.

That’s throwing a string as an exception, and that’s perfectly fine in Dart. However, with that said, it’s generally considered bad form to throw anything that doesn’t extend from the Error or Exception classes that Dart provides, so this “throw anything” is one capability you might want just to forget exists in Dart!

A couple of things are noteworthy there. First, you wrap code that might throw an exception (that you want to handle – remember, being unchecked exceptions, you never need to handle any exceptions) in a try block. Then, you catch one or more exceptions as you see fit. Here, the somethingThatMightThrowAnException() function can throw a FormatException, and we want to handle that explicitly. Then, we’ll handle any other object thrown that is a subclass of Exception and display its message. Finally, anything else thrown will be handled as an unknown exception.

Next, notice the syntactic differences there: you can write on <exception_type> catch, or you can just write catch(<object_identifier) where the object identifier is the object that was thrown under whatever name you’d like in the catch block. You can also just write on if you wish. The difference is what you need to do: if you just want to handle the exception but don’t care about the thrown object, you can just write on. If you don’t care about the type but do want the thrown object, then just use catch. When you care both about the type and also need the thrown object, use on <exception_type> catch(<object_identifier).

You can also add a finally clause to a try...catch block. This code will execute whether any sort of exception was thrown or not. This code will execute after any matching catch clauses have finished their work.

Finally, you can define your own exception classes just by extending Exception or Error. You then use them precisely as you do any Dart-provided exception.

I Have the Power: Generators

Sometimes, you have some code that produces some values. Maybe that code relies on some remote system that it needs to call. In that case, you may not want to block the rest of your code from executing while those values are generated. You instead want to generate that list in a “lazy” fashion. Alternatively, you may simply not want or be able to produce the list of values all in one shot. In these situations, a generator is something you’ll want to be familiar with

The first thing to note is the sync* marker before the body of the function. This clues Dart into the fact that this is a generator function (and a generator is always a function by the way). The second key point is the use of the yield keyword within the generator. This effectively adds the value to the Iterable that is constructed behind the scenes and returned from the function.

When called, countTo() immediately returns an iterable. Your code can then extract an iterator from that to begin iterating the result list (even though it’s not populated yet). Where it gets interesting is that countTo() won’t actually execute until the code calling it extracts that iterator and then calls moveNext() on it. When that happens, countTo() will execute until the point it hits the yield statement. The expression i++ is evaluated and is “yielded” back to the caller via the “invisible” iterator. Then, countTo() suspends (since it hasn’t met its condition for ending yet), and moveNext() returns true to its caller. Since the code using countTo() is iterating the iterator, we can read the value just yielded via its current property.

Then, countTo() resumes execution the next time moveNext() is called. When the loop ends, the method implicitly executes a return, which causes it to terminate. At that point, moveNext() returns false to its caller, and the while loop ends.

The difference here are the use of Stream as a return type and the use of the async* marker instead of *sync before the function body. Another difference is in how we use the countTo() method. Since it’s an async method, we need the function it’s called in also to be marked with async. Then, the await for is added. This is a form of for loop that is stream-aware. In a sense, because the for loop is awaiting the countTo() function to do its work, that function is effectively “pushing” the value to the for loop via the returned Stream. In this example, it may not seem obvious why you would do this, but imagine if instead of just incrementing i, countTo() instead was calling a remote server to get the next value. Hopefully, then it becomes more obvious what the value of generators is.

Metatude: Metadata

Dart also supports the notion of metadata embedded in your code. This is usually called annotations in other languages, and it kinda/sorta is in Dart too (I say it that way because the documentation calls this “metadata annotations,” which is a bit verbose, but I suppose it’s more accurate).

Dart provides two annotations, one of which you saw earlier: @override. As previously described, this is used to indicate that a class is intentionally overriding a member of its superclass.

The other annotation Dart provides is @deprecated. No, the annotation isn’t deprecated, what it marks is, silly! This marks something to indicate that you probably shouldn’t be using it anymore and that it might be removed at some point. This is especially common with a class method that will be removed in a future version of your code, but you want to give people using it a bit of time to make the change.

You can annotate the following language elements: library, class, typedef, type parameter, constructor, factory, function, field, parameter, variable declaration, and import and export directives. The metadata carried by annotations can be retrieved at runtime using Dart’s reflection capabilities, but I leave discovering that as an exercise for the reader if and when needed as its generally not needed by most people’s application code.

Speaking in General: Generics

...then Dart knows that the list ls can only contain Strings. It will enforce that type safety at compile-time.

Here, we’re telling Dart that the Things class can be used for any type, where V is a stand-in for the type (by convention, generic types like this are a single letter, most usually E, K, S, T, or V). Now, with this class serving as an interface, you can go off and implement many different versions of it, all using a different type (maybe Person, Car, Dog, and Planet, all of which could implement this same base interface).

That will print true, as you’d expect, thanks to reification. While this seems kind of obvious, it’s not the case in every language. Java, for example, uses erasure rather than reification, which means that the type is removed at runtime. So, while you can test that something is a List, you can’t test that it’s a List<String> in Java like you can in Dart.

As you can see, we can feed any type to the showFirst() method, and it can identify the type using the is keyword and act accordingly. That’s one of the key benefits of generics: you don’t need to write two different versions of showFirst(), one to handle strings and one to handle numbers. Instead, a single method can do it just fine. This isn’t necessarily the best example since just print()’ing item will work regardless of what it is, but if you wanted to do more when it’s a number, then this would be ideal.