Skip to content

Commit

Permalink
Merge pull request #68 from makimo/improvement/update-xml-section-of-…
Browse files Browse the repository at this point in the history 
…android

#66 Update XML section of Android/Kotlin
  • Loading branch information
@IwoHerka
IwoHerka committed Jul 15, 2021
2 parents 9fb981c + a6f1ee6 commit 011ea6a
Showing 1 changed file with 111 additions and 30 deletions.
141 changes: 111 additions & 30 deletions kotlin.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)
Expand All @@ -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

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -217,13 +216,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 `<layout name="...">`;

* `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`
Expand All @@ -236,49 +239,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
<!-- Bad -->
<color name="lightCerulean">#7bd3f7</color>
<color name="cerulean">#019FD9</color>
<color name="tealBlue">#007bb2</color>
<color name="pinkishRed">#F31F32</color>
```

```xml
<!-- Good -->
<color name="lightCerulean">#7bd3f7</color>
<color name="cerulean">#019fd9</color>
<color name="tealBlue">#007bb2</color>
<color name="pinkishRed">#f31f32</color>
```

```xml
<!-- Good -->
<color name="lightCerulean">#7BD3F7</color>
<color name="cerulean">#019FD9</color>
<color name="tealBlue">#007BB2</color>
<color name="pinkishRed">#F31F32</color>
```


### 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
<string name="proceed">Dalej</string>
<string name="cancel">Anuluj</string>
<string name="data_downloaded">Dane zostały pobrane</string>
<string name="error_occurred">Wystąpił błąd podczas pobiernia danych</string>
<string name="next">Next</string>
<string name="cancel">Cancel</string>
<string name="error_while_loading_data">There was a problem loading the data. Check your internet connection.</string>
```

Examples of specific strings:

```xml
<string name="reminder_date">Termin ważności: %1$s</string>
<string name="policy_number">Numer polisy</string>
<string name="coolant_type">Rodzaj płynu chłodniczego</string>
<string name="insurance_agent">Nazwa ubezpieczyciela</string>
<string name="next_event_date">Next event date: %1$s</string>
<string name="policy_number">Policy number: %1$s</string>
```

### 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
<dimen name="xsmall_padding">4dp</dimen>
Expand All @@ -287,3 +308,63 @@ Examples of specific strings:
<dimen name="large_padding">24dp</dimen>
<dimen name="xlarge_padding">32dp</dimen>
```

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
<dimen name="dim_8">8dp</dimen>
<dimen name="dim_16">16dp</dimen>
<dimen name="dim_24">24dp</dimen>
<dimen name="dim_32">32dp</dimen>
```

In the same way, you can define dimensions for text; eg.:

```xml
<dimen name="h0">48sp</dimen>
<dimen name="h1">24sp</dimen>
<dimen name="h2">20sp</dimen>
<dimen name="h3">18sp</dimen>

<dimen name="sp_4">4sp</dimen>
<dimen name="sp_8">8sp</dimen>
<dimen name="sp_10">10sp</dimen>
<dimen name="sp_14">14sp</dimen>
```

### 6. Naming styles

Similar to naming colors, styles should be as generic as possible
and correspond to their appearance or properties, not functionality.

```xml
<!-- Good -->
<style name="RedButton">
<item name=""></item>
</style>
```

```xml
<!-- Bad -->
<style name="NoInternetConnectionButton">
<item name=""></item>
</style>
```

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
<style name="RedButton">
<item name=""></item>
</style>

<style name="RedButton.Large" parent="RedButton">
<item name=""></item>
</style>

<style name="RedButton.Small" parent="RedButton">
<item name=""></item>
</style>
```

0 comments on commit 011ea6a

Please sign in to comment.