From a6f1ee6aee534333972ee9313f23b7360a317a8e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?El=C5=BCbieta=20Hofman?= Date: Wed, 14 Jul 2021 17:25:44 +0200 Subject: [PATCH] #66 Update XML section of Android/Kotlin --- kotlin.md | 141 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 111 insertions(+), 30 deletions(-) diff --git a/kotlin.md b/kotlin.md index 8a17ab2..9f2912c 100644 --- a/kotlin.md +++ b/kotlin.md @@ -6,13 +6,13 @@ in Kotlin/Android. The convention is based on [the official Kotlin style guide](https://kotlinlang.org/docs/reference/coding-conventions.html). In case of omitted aspects of code style or some differences between the company policy -and Kotlin style guide, the following document gives a preferred coding rules. +and Kotlin style guide, the following document gives preferred coding rules. ## Kotlin ### 1. Line length -Try to do not exceed 100 characters per line. In some cases it is allowed to +Try not to exceed 100 characters per line. In some cases it is allowed to use up to 120 characters. If your code line is longer than 120 characters, please look at [the official Kotlin style guide](https://kotlinlang.org/docs/reference/coding-conventions.html) to @@ -22,7 +22,7 @@ reformat a piece of code. Always use curly brackets around `if` and `when` when expression is multiline as well as around loop statements. Put the opening curly brackets at the end of -the line and the closing one on separate line aligned to the beginning of the +the line and the closing one on a separate line aligned to the beginning of the code block. ```kotlin @@ -53,7 +53,7 @@ In case of one-liners do not use brackets. if (bar) doSth() ``` -Look also at official Kotlin style guide paragraf about +Also look at the official Kotlin style guide paragraph about [formating](https://kotlinlang.org/docs/reference/coding-conventions.html#formatting) ### 3. Type declaration @@ -67,15 +67,15 @@ var y = "OK" // Good ### 4. Scope functions -Try to group code with scope functions such `apply` if possible. +Try to group code with scope functions such as `apply` if possible. ```kotlin -// BAD +// Bad val intent = Intent(this, SomeActivity::class.java) intent.putExtra(VAL_1, 1) intent.putExtra(VAL_2, 2) -// GOOD +// Good val intent = Intent(this, SomeActivity::class.java).apply { putExtra(VAL_1, 1) putExtra(VAL_2, 2) @@ -84,13 +84,12 @@ val intent = Intent(this, SomeActivity::class.java).apply { Other examples of scope functions are: `with`, `run`, `also` and `let`. -Look at official Kotlin style guide section about [using scope functions] +Look at the official Kotlin style guide section about [using scope functions] (https://kotlinlang.org/docs/reference/coding-conventions.html#using-scope-functions-applywithrunalsolet) ### 5. Expressions -Many Kotlin's structure are expressions so try to use theirs advantages if -possible. +Many Kotlin's structure are expressions so try to use theirs advantages whenever possible. #### 5.1 Control flow structures @@ -134,7 +133,7 @@ fun foo(x: Int): Int { return 2 * x } -// Bad (unless context require explicit type) +// Bad (unless context requires explicit type) fun foo(x: Int): Int = 2 * x // Good @@ -165,13 +164,17 @@ Good naming is an absolute must for an Android project. In order to make searching for Android layout files easier, we use prefixes corresponding to their function. Accordingly: +* `activity_` - Activity layout files; + +* `fragment_` - Fragment layout files; + * `layout_` - Raw layouts; imported via ``; -* `view_` - View layout files, used by widgets and small self-contained widgets; +* `dialog_` - Dialog layout files; -* `activity_` - Activity layout files; +* `item_` - List view item layout files; -* `fragment_` - Fragment layout files; +* `view_` - View layout files, used by widgets and small self-contained widgets; ### 2. Naming `drawables` @@ -184,49 +187,67 @@ to their function. Accordingly: * `view_` - Generic view layout (when other type does not fit); +* `selector_` - Selectors defining different states of components; + ### 3. Naming colors -Color names should correspond to color they represent, *not* functionality +Color names should correspond to the color they represent, *not* functionality it is related to, such as `appBarColor` or `navBarBackgroundColor`. -Those are too hard to remember. An example of good naming: +Those are too hard to remember. + +It does not matter whether the color values ​​are written in uppercase or lowercase, +But it's important to be consistent and stick to a chosen notation. + +```xml + +#7bd3f7 +#019FD9 +#007bb2 +#F31F32 +``` ```xml + #7bd3f7 #019fd9 #007bb2 #f31f32 ``` +```xml + +#7BD3F7 +#019FD9 +#007BB2 +#F31F32 +``` + + ### 4. Naming strings Strings in most applications are divided into one-time specific strings and generic informational strings, such as error-messages, confirmation -buttons, retry labels and son on. Accordingly, `strings` should reflect -this divide. Examples of generic strings used throughout the application: +buttons, retry labels and so on. Accordingly, `strings` should reflect +this division. Examples of generic strings used throughout the application: ```xml -Dalej -Anuluj -Dane zostały pobrane -Wystąpił błąd podczas pobiernia danych +Next +Cancel +There was a problem loading the data. Check your internet connection. ``` Examples of specific strings: ```xml -Termin ważności: %1$s -Numer polisy -Rodzaj płynu chłodniczego -Nazwa ubezpieczyciela +Next event date: %1$s +Policy number: %1$s ``` ### 5. Naming dimens -* All dimensions should be divisible by 2; -* When possible, dimensions should be multiples of 8, e.g.: 8, 16, 24, 32, 40, 48. -* Most projects should be two keylines - `keyline1`, `keyline2`. -* Most projects should use a finite set of standard paddings; e.g.: +When possible, dimensions should be divisible by 2, e.g.: 4, 8, 12, 16, 20, 24, 32, 50. +Most projects should use a finite set of standard paddings; e.g.: ```xml 4dp @@ -235,3 +256,63 @@ Examples of specific strings: 24dp 32dp ``` + +If the application contains a large number of dimens and naming them starts to be challenging +it's a good practice to name them based on their value; eg.; + +```xml +8dp +16dp +24dp +32dp +``` + +In the same way, you can define dimensions for text; eg.: + +```xml + 48sp + 24sp + 20sp + 18sp + + 4sp + 8sp + 10sp + 14sp +``` + +### 6. Naming styles + +Similar to naming colors, styles should be as generic as possible +and correspond to their appearance or properties, not functionality. + +```xml + + +``` + +```xml + + +``` + +It's also a good practice to separate the common base of different variants of styles, in such a case +we should specify the variant name after the `ParentName.` beginning with a capital letter; eg.; + +```xml + + + + + +``` \ No newline at end of file