[v3] Roadmap to Launch

[Stargator]

This issue is to track the Dart v3 roadmap. If you intend to help with this track, please read this entire document, and find the section about "How can you help".

@exercism/dart Please update and revise this as I pulled much of it from a template.

---

I have been working on the Dart v3 track by compiling a list of Dart specific concepts, transition documents from various languages and starting writing exercises. The concepts can be found here.

Folder structure

Specifics for Dart concepts can be found in the /info folder. There are other special folders such as /keywords, which take the keyword, and explain what they do, as they are language-specific (mostly), and the /types folder in many other languages: it lists the global objects available.

Concept exercises

The concept exercises in the Dart track are a work-in-progress and can be found in /concept-exercises. Important types of concepts to target are things that only exist in object-oriented programming (for people coming from non-oop languages), functions as a first class citizen (for people coming from non-functional languages), and Dart specifics.

It is important to understand we never explain a specific type or syntax as a concept, but teach the more "abstract" concept around it, using the type(s) or syntax(is).

A list of exercises that we must have is compiled below, and is not at all a complete list:

• [ ] /numbers: "basic-numbers", "type-conversion"
• [ ] "basic-iterables"
• [ ] "basic-errors"
• [ ] "recursion"

⚠ Note ⚠: The idea here is to use a concept name for the folder, but perhaps use some sort of "progression", so they will naturally become a sort of path to traverse. In this example, the numbers exercise only teaches basic number usage, and doesn't look into more advanced subjects. I would expect to see

• numbers-advanced for mathy usage that is non-basic,
• numbers-irrational showing how to do irrational / complex / whatever numbers,
• numbers-precision which would explore binary representation and floating points,
• numbers-arbitrary-precision which would explore bigints and/or how to do that with decimals.

It's only important that it's reasonably easy to find the exercise. It's okay if the name isn't perfect. We will iterate on this.

Concept interpretation

Here is how I've interpreted the following concept-keywords. This should be synced across tracks.

concept	interpretation
basic-numbers	Know of the existence of the number type and (for this language) see that it's whole numbers, and floating points. Know of basic operators such as multiplication. Know where it's documented, or at least how to search for it.
basic-strings	Know of the existence of the string type. Know of some basic functions (like looking up a character at a position, or slicing the string). Know where it's documented, or at least how to search for it.
futures	Know of the future construct (promise or observable type in some other languages), chain-ability, and .then. Know where it's documented/how to search.
basic-iterables	Know of the Iterable construct (array type in some other languages). Know of some basic functions.
basic-errors	Know how to create an error, how throw it and how to catch it
callbacks	Know how to use a function as a first-class citizen, that is, pass it into a function as a value, and call it somewhere inside that function. Know that you can pass in values and retrieve out return values.
recursion	Know how to call a function from itself
type-conversion	Know that there exist functions that can convert between "objects" (instances of classes) and types (primitives).

This also indicates that for example basic-strings does not include knowing that Dart strings aren't strings in the compsci sense as in, they are made up of UTF-16 codepoints, and therefore there are a lot of catches with this.

How can you help?

This track

• [x] Create a dart folder in the v3 repo.
• [ ] Files in the /info, /keywords and /types folders. They need to be written. You can use the examples from other tracks to see what we're looking for.

Globally

There are concepts missing.

Exercises

We need two types of exercises. The concept ones, as explained above -- you can chose to pick one from the list above or suggest, in this issue, one that's not listed. The other ones are the practice ones, which are like the v2 exercises.

Analyzers

TBD

[devkabiir]

Some of my thoughts:

basic-iterables Know of the Iterable construct (array type in some other languages). Know of some basic functions.

I think that in dart List would be the closest equivalent to what array is in other languages. Since dart's Map is made up of two iterables (keys, values). It might cause confusion to those that think of it as a container of two arrays. Since in other languages arrays have explicit [] and []= operators while Iterable in dart does not. List stands out to be the closest equivalent.

I also believe that with the introduction of iterable concept there should be (in the logical progression) intro to iterator, generators (sync and async).

So perhaps we could have concept progression like:

• basic-numbers
• basic-strings : Perhaps the newly introduced package characters should also be a part of this
• basic-booleans
• basic-lists
• basic-maps
• basic-iterables

type-conversion Know that there exist functions that can convert between "objects" (instances of classes) and types (primitives).

Dart doesn't have type conversion in the sense of a loosely typed language. We could call this concept type-casting, since in some dynamic/loosely typed languages type conversion does not throw any runtime errors unless something tries to access/change something in the converted object that doesn't exist at runtime. Dart also has automatic type casting, take for example:

var a = ''; // a is type casted to a String

if(a is Pattern) {
 // Scoped type casting
 // a now guaranteed to act as an object of type Pattern
}

Due to the surrounding scope of variable a dart can give us some guarantees about it's type. So I believe we could have concepts progression like

• basic-types: Know of the difference between runtimeType of an object and static type. In dart runtimeType is the real type of an object and it cannot be changed even after type casting. Perhaps include is keyword in this as well.
• type-casting: Know of it's pitfalls (specially the as vs is keyword). Automatic type casting, etc
• basic-generics: Know of dart's support for type generics and it's covariance.

Other concepts from exercism/v3#3:

• optional parameters
• mixins
• reflection: Runtime reflection (dart:mirrors) vs static reflection (package:reflectable)
• function overriding (class inheritance) Dart doesn't have function overloading

Note worthy concepts that we could discuss in future iterations:

• Streams
• Zones
• Isolates
• Event loop
• Extensions
• FFI

[devkabiir]

Should this issue be moved over to exercism/v3 repo to gain more visibility?

[Stargator]

@devkabiir I am fine with a lot of what you said. A lot of this was just to get a draft up and get the conversation started.

[iHiD]

Done :)

[Stargator]

@exercism/dart I created a first draft of a concept exercise for Futures. Please check it out and leave comments.

I'm still trying to figure out what the tests can be, I haven't used mockito uch before and that was awhile ago. If there are any suggestions for different ways to develop tests for Futures, let me know.

I also dropped concept exercises for numbers and strings. But I will likely reverse that. We want to showcase Dart's unique features/API for these, we do not try to teach CompSci to the students.

I still struggle with thinking the targeted audience already knows what some of the concepts are. But they may not know Dart's unique approach to them.

[ErikSchierboom]

I still struggle with thinking the targeted audience already knows what some of the concepts are. But they may not know Dart's unique approach to them.

I've highlighted the important part in that sentence. With v3, you're not expected to teach people what strings or numbers are (one can expect people to know about that), but you should teach people how to work with those concepts in Dart. Does that make sense?

[Stargator]

@SleeplessByte yes, that's what I was getting at. I have to constantly remind myself of that.

[md-weber]

I tried to collect all the concepts of dart to a first draft.

Concepts in Dart

• Everything is an object, every object had its instances of classes. All objects inherit from the object class
• Dart can infer types
• Dart supports generic types, like List or List
• Dart supports top level functions as well as class based and functions within functions.
• Same for Variables
• There is no keywords for private, protected and public in Dart. Instead the use of underscores (_) before an identifier to make it private.

Variables

• Variables store references.
• Default Value is null
• final variable is defined once. Though in the cases of collections (List and Set) and map, once initialized the collection or map's contents can be modified, but a new instance of the collection or map is not possible
• const is a compile-time constant and implicitly final

Built-in types

• numbers
  • int (64 bits)
  • double (IEEE 754 standard)
• strings @Stargator
  • String interpolation
• booleans (true is true and false is false. Stricter rules than JavaScript) @Stargator
• lists (also known as arrays) @Stargator
  • Spread operator
  • Null aware spread operator
  • Collectionfor / CollectionIf
• sets @Stargator
  • Same as list but can only contain unique values
• maps @Stargator
  • Key / Value pairs
• runes (Unicode in a String) @Stargator
• symbols @Stargator

Functions

• Functions are objects
• Optional parameters
• Named parameters
• Positional parameters
• Main function
• First class objects (can be contained as variable or be part of a parameter)
• Anonymous functions
• Lexical scope (scope defined by the layout)
• Lexical closures

Operators

• unary operators
• multiplicative
• additive
• shift
• bitwise operators
• relational and type test
• logical operators
• if null
• conditional
• cascade
• assignment

Control flow statements

• if / else
• break and continue
• for
• while and do-while
• switch and case
• assert

Exceptions @Stargator

• throw
• catch
• finally

Classes

• constructors @Stargator
  • named
  • redirect
  • constant
  • factory
• instance methods
• getters / setters
• abstract methods
• Abstract classes @Stargator
• Implicit interfaces
• Overriding members
• Overridable operators
• Extension methods
• Enumerated types
• Mixins @Stargator
• Static variables
• Static methods

Generics @Stargator

• collection literals
• parameterized types with constructor
• Generic collections
• restricting the parameterized type
• using generic methods

Libraries and visibility

• using library
• lazy loading a library
• implementing libraries

Asynchrony support @Stargator

• Handling futures
  • async await
  • Future API
  • try, catch finally
  • Handling streams

Generators @Stargator

• Synchronous generator
• Asynchronous generator

Callable classes

Isolates @Stargator

TypeDefs

MetaData

• @ deprecated
• @ override

Comments

• SingleLine comments
• Multiline comments
• Documentation comments

Type Safety

• if("Something not bool") => is not possible

[Stargator]

Thanks @md-weber. I did some minor edits (in bold) and fixed some typos, that's a good list.

I think the stuff in the first section (before Variables) are too high level to test. We can definitely mention these things, but most junior programmers shouldn't need concept exercises specifically for them.

Similarly for the Variables section, that may be too high level, but we sure do what to write out these concepts in our docs.

I suggest each @exercism/dart Maintainer edit the post by @md-weber. We'll do a multiple choice vote on which things each of us think would make good concepts to bring a single exercise around. Let's have the goal of finishing voting by 12:01am EST March 14th.

You would vote by tagging the concept with your username (ie: @Stargator). Concepts tagged that contain sub-bullets would include everything in the sub-bullets.

[ErikSchierboom]

This list looks nice! Some tiny nits:

• Some of the operators can probably be grouped under a single concept. For example, "bitwise AND", "bitwise XOR" and "bitwise OR" could be replaced with or grouped under the "bitwise operators" Concept.
• Some Concepts are more like descriptions. E.g. "Dart can infer types" is the "Type inference" Concept. It might help to look at the Concepts identified for the C# language: https://github.com/exercism/v3/blob/master/languages/csharp/reference/README.md#c-reference

[Stargator]

Linking a conversion that was ongoing in the Dart track here. As many other concepts were brought up. https://github.com/exercism/dart/issues/174