Add a "design discussion" section to the setState method

[konmik]

I just started playing with Flutter, and the most obvious stuff is setState. Honestly, it does not look good. Why would you want to put all your mutations into a lambda, especially if they are all side-effecting? Wouldn't it be better just to call update() directly after you do all the state mutations?

The pattern looks like it came from a functional architecture, but the main point is missing - state mutation should have been encapsulated inside setState function, but this is not the case for Flutter. Without immutability, pure lambda and state change encapsulation all of this doesn't seems have any meaning.

[Hixie]

We used to just have a markNeedsBuild method but we found people called it like a good luck charm -- any time they weren't sure if they needed to call it, they'd call it.

We changed to a method that takes a (synchronously-invoked) callback, and suddenly people had much less trouble with it. We found people understand much more easily that if you didn't change any state, you don't need to call it; if you did change some state, you call it and change the state during the call.

Eventually we plan to make some lints verify that anything you use in your build function you only set from setState, to catch cases where people set things but don't notify the framework.

[Hixie]

I'll add a "Design discussion" section to the setState docs talking about this. Let me know if there's anything else you'd like covered in the docs for this, I'm happy to add more information there.

[konmik]

Maybe the better docs was needed for markNeedsBuild? Or just rename it to onStateChanged() or whatever? Lambda instantiation is not free, it adds needless code nesting, it also increases cognitive code complexity and puzzles more experienced devs (me :D).

Otherwise, thanks for the explanation! :)

[Hixie]

Maybe the better docs was needed for markNeedsBuild?

Maybe, but in my experience we shouldn't depend on people reading API docs. :-)

Or just rename it to onStateChanged() or whatever?

That would be inconsistent with our naming guide: https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#naming-rules-for-typedefs-and-function-variables

Lambda instantiation is not free

It's a pretty small cost when called once per frame (which is what you generally expect for setState). Also, it's not called during performance-critical periods; it's called in response to user input generally and so we have more CPU to play with here than if it was during the frame itself. Also eventually I wouldn't be surprised if we were able to get the compiler to just inline this.

it adds needless code nesting

Needless is subjective here. I would argue the need is to show that this is the block that is actually mutating the state.

it also increases cognitive code complexity

Well as noted above, in practice it seems to have actually reduced it.

and puzzles more experienced devs (me :D).

Yup, that's why we need to add more to the documentation. :-)

[tvolkert]

Closing, as there are several places in our documentation nowadays that talk about setState() and state management.

[mateusfccp]

Eventually we plan to make some lints verify that anything you use in your build function you only set from setState, to catch cases where people set things but don't notify the framework.

@Hixie Is there any issue tracking this?