diff --git a/README.md b/README.md index c06d914..4d343db 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,10 @@ flutter run New to Flutter? See [Getting Started](/documentation/GETTING_STARTED.md) for full setup and run instructions. +Each example app is split into a wrapper and focused code. `lib/main.dart` sets up +the `MaterialApp`, and `lib/example.dart` contains the code that demonstrates the +concept. Open `lib/example.dart` to see what the app teaches. + ## Documentation - [Example Apps](/documentation/EXAMPLES.md): all examples in this repository diff --git a/documentation/CONTRIBUTING.md b/documentation/CONTRIBUTING.md index 0c8047d..3899194 100644 --- a/documentation/CONTRIBUTING.md +++ b/documentation/CONTRIBUTING.md @@ -2,6 +2,23 @@ I welcome and encourage all pull requests. It usually takes 24-48 hours to respond to any issue or request. +## Example app structure + +Every example app uses the same structure, so the code that teaches a concept is +easy to find: + +- `lib/main.dart`: the app wrapper. It holds only `runApp()` and a `MyApp` widget + that returns the `MaterialApp` (title, theme, routes). Keep this file minimal and + uniform across apps. +- `lib/example.dart`: the focused example code. It contains the full screen + (`Scaffold` + `AppBar`) and the widget that demonstrates the concept, with a + `// Example: ` comment at the top. +- Supporting files (screens, tabs, services, models, widgets, utils) sit alongside + the example and are imported by `lib/example.dart`. + +To understand an example app, read `lib/example.dart`. That file holds the concept; +`lib/main.dart` holds only the wrapping boilerplate. + ## Basic rules 1. Match coding style (braces, spacing, etc.). Use the `Reformat Code` feature of Android Studio (`CMD` + `Option` + `L` on Mac, `CTRL` + `ALT` + `L` on Linux and Windows). @@ -11,3 +28,7 @@ I welcome and encourage all pull requests. It usually takes 24-48 hours to respo 1. Check for existing [issues](https://github.com/nisrulz/flutter-examples/issues) before filing a new one. 1. Follow the same standard as all other projects in this repo. > The package name must conform to the format: `github.nisrulz.` + +When you add a new example app, keep the wrapper in `lib/main.dart` and the focused +example code in `lib/example.dart`. Run `make docs`, `make analyze`, and `make doctor` +before opening a pull request. diff --git a/documentation/GETTING_STARTED.md b/documentation/GETTING_STARTED.md index 2de314f..20c66db 100644 --- a/documentation/GETTING_STARTED.md +++ b/documentation/GETTING_STARTED.md @@ -30,6 +30,14 @@ cd simple_material_app flutter run ``` +## Where to look for the example code + +Every example app is split into two files: + +- `lib/main.dart`: the app wrapper. It only sets up the `MaterialApp` (title, theme, routes). +- `lib/example.dart`: the focused example code. This file teaches the concept the + app demonstrates. Open it to see how the feature works. + ## Useful links - [Flutter Widgets Catalog](https://flutter.dev/widgets/)