From 47bc42b0afa866a275782ab13f86c3bad7196788 Mon Sep 17 00:00:00 2001 From: Vadim <44135514+vodemn@users.noreply.github.com> Date: Wed, 25 Jan 2023 12:47:35 +0300 Subject: [PATCH] added style guide --- README.md | 21 ++++--- doc/style_guide.md | 144 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 157 insertions(+), 8 deletions(-) create mode 100644 doc/style_guide.md diff --git a/README.md b/README.md index e1d6ab6..e57bddf 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ Material Lightmeter

-## 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. @@ -13,18 +13,19 @@ 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) -## Table of contents +# Table of contents - [Backstory](#backstory) - [Table of contents](#table-of-contents) - [Legacy features](#legacy-features) - - [Metering](#metering) - - [Adjust](#adjust) - - [General](#general) - - [Theme](#theme) -- [Build](#build) + - [Metering](#metering) + - [Adjust](#adjust) + - [General](#general) + - [Theme](#theme) + - [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. @@ -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 ``` + +## Contribution + +In case you want to help develop this project you need to follow this [style guide](doc/style_guide.md). \ No newline at end of file diff --git a/doc/style_guide.md b/doc/style_guide.md new file mode 100644 index 0000000..d2ad23f --- /dev/null +++ b/doc/style_guide.md @@ -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: +- ** + - bloc_**.dart + - provider_**.dart + - widget_**.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: +- ** + - widget_**.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, +) +``` \ No newline at end of file