View on GitHub

Povio Engineering Guidelines

These are guidelines for the technologies we are using.

Android Kotlin/Java Code Guidelines

Android Logo

Please read the following chapters before jumping in

  1. Coding language
  2. Supported Android Versions
  3. Gradle
  4. Code style
  5. App architecture
  6. Recommended libraries and frameworks
  7. Automated tests
  8. Git
  9. Code reviews
  10. Staging and production deployment
  11. Android Studio
  12. Books and resources

Coding language

Our language of choice is Kotlin for all new Android application. An exception are existing projects written in Java.

Supported Android versions

Gradle

All new projects should use Gradle’s Kotlin DSL. An exception are existing projects written in Groovy DSL. All configurations, library versions, ect. should be kept in the buildSrc module.

Here are a few handy snippets:

object ProjectVersions {
    private const val versionMajor = 1
    private const val versionMinor = 0
    private const val versionPatch = 0
    private const val versionBuild = 0

    const val versionCode = versionMajor * 1000000 + versionMinor * 10000 + versionPatch * 100 + versionBuild
    const val versionName = "$versionMajor.$versionMinor.$versionPatch.$versionBuild"
    const val archivesBaseName = "[NameOfProject]-$versionName"
}

Always include links above versions

    //https://mvnrepository.com/artifact/androidx.test.ext/junit
    const val androidJUnitVersion = "1.1.1"

Explain beta version inclusion under link

//https://developer.android.com/jetpack/androidx/releases/constraintlayout
//[ConstraintLayout 2.0.0-beta1] NPE when calling MotionLayout.transitionToState https://issuetracker.google.com/issues?q=132473209	
const val constraintLayoutVersion = "2.0.0-beta3"

Code style

Follow the Official Kotlin Style Guide and Android Kotlin style guide.
Follow the Google Java Style Guide for Java code formatting.

Enable the following options in Android Studio’s before commit portion of the commit dialog:

Before Commit Options

Best practices

Automatic code formatting & checks

To automate checking that the code follows the guidelines and code formatting use ktlint - a Kotlin linter with a smart default rules matching the official Kotlin code style.
Ktlint Gradle plugin provides the following Gradle tasks (among others):

App architecture

All new applications should adopt Model View ViewModel (MVVM) architecture pattern, leveraging Android Architecture Components. See Google’s recommended app architecture for reference.

The recommended stack for Kotlin is:

Any differences should be discussed with the project’s tech lead.

Project structure

Package by Feature motivation

com/app/
    activity
        BaseActivity.kt
    fragment
        BaseFragment.kt
    useCase
        BaseUseCase.kt
    database
        AppDatabase.kt
    login
        LoginFragment.kt
        LoginViewModel.kt
        LoginService.kt
        LoginDataClass.kt
    user
        UserRepository.kt 
        UserRemoteDataSouce.kt
        UserLocalDataSource.kt
        UserService.kt
        UserDao.kt
        UserModel.kt
    userList
        UserListFragment.kt
        UserListViewModel.kt
        UserListUseCase.kt
        UserListWorker.kt
        UserListModel.kt
    userDetails
        UserDetailsFragment.kt
        UserDetailsViewModel.kt
        UserDetailsUseCase.kt
        UserDetailsModel.kt

Styles

Localization

  1. Every project should have it’s own google Sheet named like <ProjectName> - Localization. Please ask your PM or lead developer to create one and give you read/write access.
  2. Create the following Gemfile in project root: ```ruby source “https://rubygems.org”

gem ‘babelish’ gem ‘google-api-client’ gem ‘activesupport’

3. Create folder named `Localize` and copy files from [sample](/code-guidelines/android/resources/localization_scripts.zip) zip file
4. Look for further instructions in `Localize/README.txt`

#### App configuration
Use Android productFlavors as well as buildTypes for app configuration across dev/staging/production.

Always include a signing config for debug and commit the debug.keystore to version control.

signingConfigs { getByName(“debug”) { storeFile = file(“debug.keystore”) storePassword = “android” keyAlias = “androiddebugkey” keyPassword = “android” } } ```

The basic idea is to encourage you to use popular, top rated and evolving libraries only. Allways consider if one of Jetpack’s libraries will solve your issue before considering external sources. If you need access to any of the mentioned services, check who is responsible for that service on Vendors & Administrators and contact them.

DO NOT

List of libraries you should consider using:

Networking and data manipulation

* If you are not familiar with this library, get familiar with it ASAP (you should know all of the libraries from the list but these are a must).

List of services you should consider using:

Automated tests

We should strive towards practicing TDD.

The developer should make a conscious effort to write tests early and often. Every feature should have backing tests before pushing it to git. The developer should locally run all Unit test related to the story and verify they pass before pushing. Features should have mostly unit tests, but also a smaller number of end-to-end test for user flows or whole screens and sometimes integration tests to check integration between two or more units.
For a detailed guide, check the Android documentation.

The developer can rely on CI to run the full test suite. Use circle.yml (wip) as a starting point for CircleCI configuration.

Development tools

Tools for display and control of connected Android devices. Useful for sharing the device screen for pairing or live demos.

Performance

Security and optimizations

Git

The Git guidelines are a part of the general guidelines. Be sure to read them as well.

Code reviews

Keep the branches as small and relevant as possible to avoid huge PRs. Each project will have a lead developer on it, he will review the code before merging/squashing it to the base branch.

Staging and production deployment

Leverage Play Console’s Internal test track and Closed track - Alpha for distributing build previews.

Android Studio

Android Studio is something you are using daily and it is one of your main tools. You should not only be comfortable using it but be fast and efficient as well. You should create a cozy and familiar environment:

Useful Android Studio shortcuts

Knowing the shortcuts for actions that you repeat often is paramount. It will save you a lot of time and will streamline your development process. There are two categories of shortcuts you should be using:

  1. Shortcuts for actions that you do often (use the Key Promoter plugin).
  2. Shortcuts for actions that you do not use but should (take a look at the list below for some examples).

List of some useful shortcuts:

Books and resources

Java