added style guide

This commit is contained in:
Vadim 2023-01-25 12:47:35 +03:00
parent 2e523d12de
commit 47bc42b0af
2 changed files with 157 additions and 8 deletions

View file

@ -5,7 +5,7 @@
<b>Material Lightmeter</b> <b>Material Lightmeter</b>
</p> </p>
## Backstory # Backstory
Some time ago I've started developing the [Material Lightmeter](https://play.google.com/store/apps/details?id=com.vodemn.lightmeter&hl=en&gl=US) app. Unfortunately, the last update of this app was almost a year prior to creation of this repo. So after reading some positive review on Google Play saying that "this is an excellent app, too bad it is no longer updated", I've decided to make an update and also make this app open source. Maybe someone sometime will decide to contribute to this project. Some time ago I've started developing the [Material Lightmeter](https://play.google.com/store/apps/details?id=com.vodemn.lightmeter&hl=en&gl=US) app. Unfortunately, the last update of this app was almost a year prior to creation of this repo. So after reading some positive review on Google Play saying that "this is an excellent app, too bad it is no longer updated", I've decided to make an update and also make this app open source. Maybe someone sometime will decide to contribute to this project.
@ -13,7 +13,7 @@ But as the existing repo contained some sensitive data, that I've pushed due to
Without further delay behold my new Lightmeter app inspired by Material You (a.k.a. M3) Without further delay behold my new Lightmeter app inspired by Material You (a.k.a. M3)
## Table of contents # Table of contents
- [Backstory](#backstory) - [Backstory](#backstory)
- [Table of contents](#table-of-contents) - [Table of contents](#table-of-contents)
@ -23,8 +23,9 @@ Without further delay behold my new Lightmeter app inspired by Material You (a.k
- [General](#general) - [General](#general)
- [Theme](#theme) - [Theme](#theme)
- [Build](#build) - [Build](#build)
- [Contribution](#contribution)
## Legacy features # Legacy features
The list of features that the old lightmeter app has and that have to be implemeneted in the M3 lightmeter. The list of features that the old lightmeter app has and that have to be implemeneted in the M3 lightmeter.
@ -55,3 +56,7 @@ The list of features that the old lightmeter app has and that have to be impleme
``` ```
flutter build apk --flavor dev --dart-define cameraPreviewAspectRatio=2/3 -t lib/main_dev.dart flutter build apk --flavor dev --dart-define cameraPreviewAspectRatio=2/3 -t lib/main_dev.dart
``` ```
## Contribution
In case you want to help develop this project you need to follow this [style guide](doc/style_guide.md).

144
doc/style_guide.md Normal file
View file

@ -0,0 +1,144 @@
This repo uses [Effective Dart Style](https://dart.dev/guides/language/effective-dart/style) and [Style guide for Flutter repo](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#formatting) with some alterations.
## Table of contents
- [Table of contents](#table-of-contents)
- [Folder structure guidelines](#folder-structure-guidelines)
- [Inverse file naming](#inverse-file-naming)
- [Always use a functional prefix in widgets file names](#always-use-a-functional-prefix-in-widgets-file-names)
- [All files must be grouped according to their function](#all-files-must-be-grouped-according-to-their-function)
- [Place elements used by one screen in the folder of this screen](#place-elements-used-by-one-screen-in-the-folder-of-this-screen)
- [Place elements used within one logical group in the _shared_ folder inside this group folder](#place-elements-used-within-one-logical-group-in-the-shared-folder-inside-this-group-folder)
- [Always place component in its own folder](#always-place-component-in-its-own-folder)
- [Formatting](#formatting)
- [Prefer maximum line length of 120 characters](#prefer-maximum-line-length-of-120-characters)
- [Omit trailing comma after single parameter](#omit-trailing-comma-after-single-parameter)
## Folder structure guidelines
### Inverse file naming
We use inverse names for files, but a regular one for folders.
```
.
└── settigns/
├── fractional_stops/
│ └── widget_list_tile_fractional_stops.dart
├── ...
└── screen_settings.dart
```
```dart
/// widget_list_tile_fractional_stops.dart
class FractionalStopsListTile extends StatelessWidget {...}
```
```dart
/// screen_settings.dart
class SettingsScreen extends StatelessWidget {...}
```
### Always use a functional prefix in widgets file names
Basically this rule comes from the previous one but covers specifically widgets.
It is pretty obvious that for example `FooIcon` and `BarButton` are widgets and respective file names *icon_foo.dart* and *button_bar.dart* reflect it. But we still add *widget_* prefix to all widgets to maintain consistency while omitting `Widget` in the class names (i.e. `FooIconWidget`).
### All files must be grouped according to their function
That basically means, that all files should be placed in the folders according to their functional prefix even if there is only one file.
### Place elements used by one screen in the folder of this screen
Place all widgets, utils, etc. used by a single screen in corresponding folders on the same level with other screen files.
```
.
└── screens/
└── metering/
├── components/
│ ├── bottom_controls/
│ │ └── ...
│ └── topbar/
│ └── ...
└── screen_metering.dart
```
### Place elements used within one logical group in the _shared_ folder inside this group folder
Components used by multiple screens or by other components within one logical group should be placed in the _shared_ folder on the same level with the corresponding screens/components.
In the example below the `DialogPicker` is used by `FractionalStopsListTile` and `ThemeTypeListTile`.
```
.
└── settigns/
├── fractional_stops/
│ └── widget_list_tile_fractional_stops.dart
├── shared/
│ └── dialog_picker/
│ └── widget_dialog_picker.dart
└── theme_type/
└── widget_list_tile_theme_type.dart
```
### Always place component in its own folder
Folder structure for the most basic widget looks like this:
- *<widget_name>*
- bloc_*<widget_name>*.dart
- provider_*<widget_name>*.dart
- widget_*<widget_name>*.dart
But sometimes widgets don't need a bloc and provider and therefore there is only one file left - the widget itself.
Even in this case a single file has to be placed in its own folder:
- *<widget2_name>*
- widget_*<widget2_name>*.dart
```
/// BAD
components/
├── haptics/
│ ├── bloc_list_tile_haptics.dart
│ ├── provider_list_tile_haptics.dart
│ └── widget_list_tile_haptics.dart
└── widget_list_tile_theme_type.dart
/// GOOD
components/
├── haptics/
│ ├── bloc_list_tile_haptics.dart
│ ├── provider_list_tile_haptics.dart
│ └── widget_list_tile_haptics.dart
└── theme_type/
└── widget_list_tile_theme_type.dart
```
## Formatting
### Prefer maximum line length of 120 characters
Just an alteration of the Style guide [rule](https://github.com/flutter/flutter/wiki/Style-guide-for-Flutter-repo#prefer-a-maximum-line-length-of-80-characters) changing the maximum line length from 80 to 120 characters.
### Omit trailing comma after single parameter
```dart
/// BAD
const SizedBox(
width: 16.0,
)
/// ALSO BAD
const SizedBox(width: 16.0, height: 16.0)
/// GOOD
const SizedBox(width: 16.0)
/// ALSO GOOD
const SizedBox(
width: 16.0,
height: 16.0,
)
```