brianegan / brianegan/flutter_architecture_samples

Add "App Flow" comments to code

Open
#19 1 comment 3 reactions 0 assignees View on GitHub
Dominant language
Dart
Stars
8.9k
Forks
1.7k
PR merge metrics
No merged PRs in 30d

Description

I've gotten feedback that this library, asking for more comments within the code demonstrating the flow of these apps.

- [ ] vanilla
- [ ] redux
- [ ] built_redux
- [ ] inherited_widget
- [ ] scoped_model

Example from Scott Stoll:

```dart
import "1_main.dart";
import '5_MyInheritedWidget.dart';
import '6_MiddleWidget.dart';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'dart:convert';

/*Brian,
Use the TODOs to follow the logic of how this code flows. Hopefully you'll
agree that this explains what's going on here clearly enough that a 5 year old
could follow it. "Explain it to me like I'm 5" is a great way to go when
trying to teach someone things for their very first time. There are more notes
at the bottom of the page, after you're done.*/

class BaseStatefulWidgetState extends State with WidgetsBindingObserver {
// TODO (1) var "name" will store the current name during rebuild, much like "Saved Instance State" would in Android
// TODO (6) Store the new name here, then go rebuild
String name = '..loading';

static const int _NUMBER_OF_USERS = 10;

// TODO (2) 'i' is used to track which record we want within the JSON data
int i = 0;

onTap() {
// TODO: (3) User has tapped. Incrementing i tells us which name to get from the JSON data next (1st, 2nd, etc.).
i++;
_getName();
}

@override
void didChangeAppLifecycleState(AppLifecycleState appLifecycleState) {
}

_getName() async {
// TODO (4) Start async task for JSON operation. Fetch data & get name for record number 'i'
var res = await http.get('https://jsonplaceholder.typicode.com/users');
var name = JSON.decode(res.body)[i % _NUMBER_OF_USERS]['name'];

// TODO (5) Send the name value of the above record to the global var "name" and trigger setState
setState(() => this.name = name);
}

@override
void initState() {
super.initState();
_getName();
WidgetsBinding.instance.addObserver(this);
}

@override
void dispose() {
WidgetsBinding.instance.removeObserver(this);
super.dispose();
}

@override
void didChangeDependencies() {
super.didChangeDependencies();
}

@override
Widget build(BuildContext context) {

// TODO (6) Notice that MyInheritedWidget is built / rebuilt with the current global name value.
return new MyInheritedWidget(

// TODO (7) MyInheritedWidget has the child MiddleWidget, so the UI widgets are going to be children of MyInheritedWidget
name: name, onTap: onTap, child: const MiddleWidget());
}
/*From here the code leaves this class and goes to another class that builds the rest of the UI,
including a text field that contains the updated name. The overall point is that, when dealing with a file
people are supposed to be learning from, we really want to idiot proof the explaination of how the code
flows.It's only when people understand the overall structure and how it flows that they'll be able to
go on and implement it in their own creations. By using a TODO list, the student can move from step
to step with a simple mouse click.

Of course, in the working world, code that people are not trying to learn from should merely be expressive
enough that people who are already familiar with the SDK will be able to follow.*/
}
```

Contributor guide

Open the contributing guide

Research direction

Review the five example areas listed in the issue—vanilla, redux, built_redux, inherited_widget, and scoped_model—and begin with the referenced entry files such as 1_main.dart, 5_MyInheritedWidget.dart, and 6_MiddleWidget.dart. Trace each app's flow and add explanatory comments so every listed example is covered and a learner can follow how the code moves between its components.

Written by the indexing model from the issue text.

Assessment

Tech stack
dart, flutter
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.