Doc: "Flutter for the react.js developer"

[sethladd]

It would be interesting to write a document that specifically talks to JavaScript and react.js developers. There are enough similarities and differences that we could probably use a doc for this.

[sethladd]

cc @appsforartists

[appsforartists]

I'd be happy to help out with this. It's fairly similar, but I would lean closer to the JS style in Dart (instead of Java-esque feel of the current tutorial). Use var. Use this.varName. Define the instance properties before the constructor. Make things easy to read for someone who's experienced in JS.

FWIW, I wrote this pen yesterday while I was going through the tutorial. It's a port of the Counter example to React. Notice how simple the LabeledValue component is? It would be sweet if stateless Flutter components were just pure functions (effectively, the current build without the class).

[abarth]

Use var.

There are two reasons we don't use var:

1. Documentation. We assume developers will read the framework code to learn how to use the system, particularly advanced users who want to take advantage of the powerful, low-level constructs. Using type annotations means more typing for us but makes the code more self-documenting.
2. Analyzer. Using var makes it harder for the analyzer to produce errors and warnings and it makes it harder for the IDE integration to produce good code completions. Eventually, we might require programs to pass some set of analyzer flags in order to get fast ahead-of-time builds.

Use this.varName.

The reason we don't use this.varName is just because its more typing and doesn't add any value.

Define the instance properties before the constructor.

I'd be fine with this style change. If we make this change, we should update the entire codebase rather than having one piece of documentation randomly in a different style. @Hixie is in charge of Flutter style, so if you convince him to make this change, I can help you reformat the codebase.

It would be sweet if stateless Flutter components were just pure functions

Having an immutable object to represent stateless components enables us to do important performance optimizations. In particular, suppose you pass widget A to widget B and B incorporates it into its build. When widget B rebuilds, we can tell whether we need to rebuild widget A by comparing the object identity of the instance.

There are several situations where we pass around WidgetBuilder objects instead of Widget objects. A WidgetBuilder is essentially a (possibly pure) functional representation of a Widget. However, using that pattern everywhere would harm performance.

[sethladd]

For the tutorial, it would be interesting to start with a more JS-esque style (to reduce the amount of differences) and then, once some of the Flutter concepts are explained, we then go into the Dart concepts. "OK, now that you've seen how Flutter works, let's show you how to scale the code up, by adding type annotations." and then explain why Flutter uses type annotations.

Also, as a second step, remove the this.varName and explain why we don't need it.

We could start with the builders, and then "upgrade" to the full classes.

I think it's all about growing this doc's code over time, introducing one new concept at a time. The feedback we got was "I know JS and React.js, but when I took a look at Flutter, there were too many different things all at once."

[appsforartists]

There are two reasons we don't use var: Documentation and the Analyzer

Tutorials should provide an accessible way for people new to the language to learn it. They should teach the minimum amount you need to understand at the beginning, and then layer on complexity: progressive disclosure. One way to think about it: would you rather climb 10 steps or a 10' wall? The tutorial right now is information overload. It's like climbing the wall. We should make it more like climbing stairs.

As someone who's familiar with JavaScript, beginning every line/statement with a type annotation makes it harder for me to see the mechanics of the framework. (It feels like clutter.) That makes it harder to follow and to learn, even if Google prefers types for production code.

particularly advanced users

The target audience of the introduction should be a lot wider than "advanced users"

The reason we don't use this.varName is just because its more typing and doesn't add any value.

The value it adds is familiarity to newcomers. This is the distinction between the tutorial and the style guide. JavaScript developers understand this.name notation and will have an easier time following a tutorial if you use it. Removing this.name might be something you can layer-in in more advanced tutorials (like adding type annotations), but if you remove it at the beginning it starts to turn your 10 steps into a 10' wall. Minimize the number of things people need to think about when they are learning.

I'd be fine with this style change. If we make this change, we should update the entire codebase rather than having one piece of documentation randomly in a different style. @Hixie is in charge of Flutter style, so if you convince him to make this change, I can help you reformat the codebase.

For me, it's a huge readability improvement. It's easier to understand what the constructor is setting if you have already seen the scope of things it could be setting. It's also easier to follow without having to understand the mechanics of hoisting.

Having an immutable object to represent stateless components enables us to do important performance optimizations.

Is this an implementation detail leaking out? It seems like the way you represent them internally doesn't necessarily need to dictate the external API.

Moreover, if you had a pure function:

var LabeledValue = (label, value) => new Text("$label: $value");

// or perhaps
var LabeledValue = (props) => new Text("$props.label: $props.value");

the state that gets passed around is the immutable object you could compare. Doesn't seem like the component itself needs to serve that role.

[krisgiesing]

There are often tables in such documentation that say "If you do A in system X, you do B in system Y". It might be useful in this case to have a third column: "If you do A in JavaScript, the most direct/obvious translation is B in Dart. But it's more idiomatic (shorter/more convenient/more performant) to do C instead".

[Hixie]

We should definitely have a "Flutter for Web engineers" tutorial. The current tutorial is really "Flutter for Dart engineers"; it doesn't make any effort to explain Dart concepts, only Flutter concepts.

[appsforartists]

@Hixie - thoughts on moving the public var definitions above the constructor definition?

[Hixie]

Our style guide encourages members to be grouped together in logical groups, for example, all the layout logic, then all the painting logic, then all the hit-testing logic, etc. So members should be grouped with the rest of the stuff that deals with whatever they deal with. They should especially be grouped with their setters and getters when they have them. Having fields in one place and other code that refers to them in another leads to less maintainable and less readable code because you have to jump up and down to find what's going on (especially to find the type annotations).

Constructors should come first because they run first. Our style guide encourages putting code in the order that it runs in normal operation, so constructors first, and functions like dispose() last. Setters for member fields run immediately after a constructor is called, so they (when they aren't grouped with relevant functions) go immediately after the constructors. Having the constructors first is important for readability as well. It makes it clear how you can get an instance of the class, along with the API that that construction mechanism has.

Also, putting the constructors first dramatically improves maintainability when creating new classes by copying other classes: since Dart doesn't have a constructor keyword or equivalent, and instead names constructors by duplicating the class name, you want to put all the instances of that class name as close together as possible, so that when you copy the class, you see all the places you should change straight away. Not doing this can lead to some very subtle and hard-to-diagnose bugs, because the cases you forget to rename are still syntactically correct in many cases, and thus don't get caught by the compiler.

[abarth]

Is this an implementation detail leaking out?

That's often the cause for API decisions that are geared towards performance.

We've made lots of decisions in the structure of the framework's API to gently guide developers towards patterns that are faster because of implementation details. For example, Container doesn't have any clipping facilities because clipping is more expensive in the implementation. Similarly, adding a borderRadius doesn't imply an RRect clip because RRect clips are more expensive that rectangular clips.

The overall style of the framework is inspired by React.js, but we've done a number of things in different ways, largely for specific reasons. In particularly, we've decided to use objects rather than closures in most places in order to let us perform some performance optimizations that don't exist in react. That decision ends up propagating throughout the system, including making StatelessComponents objects rather than closures.

[abarth]

By the way, you might be interested in the Builder widget:

http://docs.domokit.org/flutter/material/Builder-class.html

That widget let's you make a Widget out of a WidgetBuilder.

[sethladd]

Lovely idea, and we'd love to see this pop up, but it's not currently planned.