Skip to main content

Android best practices

General principles​

In general, we should follow standard development principles such as:

  • SOLID: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion. Learn more with Kotlin SOLID Principles Examples
  • KISS: Keep It Simple, Stupid.
  • DRY: Don't Repeat Yourself
  • Community guidelines: Follow the practices showcased in the NowInAndroid repository.

Documentation​

Documentation in the code should bring value and evolve with the codebase. Keep the following in mind:

  • Stay up-to-date: Documentation must be updated as the code changes.
  • Balance comments: Avoid over-commenting, but don’t forget to comment where necessary.
  • Future-proof: Ask yourself, "Will I understand what I did in 6 months?"
info

Documentation should help, not hinder.

Logging​

Logging is essential but should be used judiciously. As Jake Wharton says in his Timber library:

Every time you log in production, a puppy dies.

  • Avoid excessive logging in production.
  • Use structured and meaningful log messages.
  • Leverage tools like Timber to manage logging effectively.

Time and duration​

When working with time, date, or duration, avoid using primitive types. Instead, use strong types to prevent unit mix-ups.

❌ Don't do this​

const val THRESHOLD = 600000

fun main() {
    val now = System.currentTimeMillis()
    
    if (now > THRESHOLD) {
        // Do something
    }
}

✅ Do this​

val THRESHOLD = Instant.ofEpochSecond(60)

fun main() {
    val now = Instant.now()

    if (now > THRESHOLD) {
        // Do something
    }
}
warning

If you must use primitive types, ensure the variable name includes the unit (e.g., THRESHOLD_MS instead of THRESHOLD) to reduce ambiguity.

  • Apply the same logic to dates, durations, and timestamps.
  • For APIs that use long for timestamps (e.g., milliseconds vs. seconds), convert the values to a strong type as soon as possible to minimize exposure to untyped units.

Concurrency​

Concurrency is powerful but requires careful handling to avoid issues like memory leaks and race conditions.

Coroutine scope​

Tie your coroutines to an Android lifecycle (e.g., viewModelScope or lifecycleScope) to prevent memory leaks.

Concurrent access​

  • Ensure that any references accessed outside of a coroutine are thread-safe.
  • If a reference is not safe, either make it safe or don't use it.
  • Debugging concurrency issues (e.g., race conditions) can be extremely challenging, so design carefully.

For more details on race conditions, see Race Condition.

Code organization​

Keep your classes small​

  • Large classes often have too many responsibilities, making them harder to review, test, and maintain.
  • Aim for small classes with proper separation of concerns and abstraction.

Keep your functions small and meaningful​

  • Functions should be small and focused on a single responsibility.
  • A function's name should clearly describe what it does. If it’s hard to name, the function likely does too much.
  • Well-named, small functions reduce the need for documentation and make the code self-explanatory.
note

Naming is hard, but smaller functions make it easier to choose meaningful names.

Keep your PRs small​

  • Why? Smaller PRs are easier to review, reduce delays, and minimize frustration.
  • How? Break down large changes into smaller, logical chunks.

For more details, see submit.

Additional notes​

  • Testing: Write unit tests for critical functionality to ensure reliability.
  • Code reviews: Always review code for adherence to these best practices.

Fail fast​

The further you progress in development, the more difficult it becomes to debug issues. Do not ignore errors, even those you think are unlikely to occur. Always aim to catch errors at build time rather than at runtime. Use Kotlin compiler features whenever possible, and consider adding a lint rule if you cannot enforce a check at compile time.

Leverage Kotlin compiler​

The Kotlin compiler can help you catch issues early. For example, using the when operator with sealed classes/interfaces ensures that all cases are handled.

Example:

sealed interface Shape {
    class Rectangle: Shape
    class Oval: Shape
}

fun foo(shape: Shape) {
    when(shape) {
        is Shape.Oval -> TODO()
        is Shape.Rectangle -> TODO()
    }
}

If you add a new class that implements Shape, the compiler will fail to build until you handle the new case. This is especially useful when the interface is used throughout the codebase. Note that this only works if you do not add an else branch.

Don't silently ignore exceptions​

While it is important to catch exceptions to prevent crashes, silently ignoring them can hide deeper issues and make debugging more difficult. For example, consider a third-party library that requires initialization with an API key. If initialization fails and the exception is caught without proper logging, it can be challenging to identify the root cause if something stops working.

Example:

fun foo() {
    
    // Always catch the error and proceed with fallback value
    val value = try {
        ExternalThirdPartyJavaAPI.value()    
    } catch (e: Exception) {
        // Fortunately we log the error to help with troubleshooting
        Timber.w(e, "Couldn't get ExternalThirdParty value, current state: ${ExternalThirdPartyJavaAPI.state()}")
        "fallback"
    }
}

Proper logging ensures that users and developers can spot errors in the logs and report issues effectively.

To further improve error handling during development, use the FailFast API. This API applies offensive programming principles by crashing the app in the debug flavor when an error occurs, making issues more visible early in the development process.

Example:

import io.homeassistant.companion.android.common.util.FailFast

fun foo() {

    // In case of a failure, this will print a message and stack trace to the logs. In debug builds, it
    // will also crash the app, while in production it will use the fallback value instead of crashing.
    val value = FailFast.failOnCatch(
        message = { "Couldn't get ExternalThirdParty value, current state: ${ExternalThirdPartyJavaAPI.state()}" },
        fallback = "fallback",
    ) {
        ExternalThirdPartyJavaAPI.value()
    }
}

By failing fast and logging errors clearly, you make it easier to identify, debug, and fix issues before they reach production.

When the FailFast API is triggered, it produces a clear and visible log entry, making it easy to spot and investigate:

2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  ██████████████████████
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  !!! CRITICAL FAILURE: FAIL-FAST !!!
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  ██████████████████████
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  An unrecoverable error has occurred, and the FailFast mechanism
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  has been triggered. The application cannot continue and will now exit.
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  ACTION REQUIRED: This error must be investigated and resolved.
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  Review the accompanying stack trace for details.
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  ----------------------------------------------------------------
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  io.homeassistant.companion.android.common.util.FailFastException: Couldn't get ExternalThirdParty value, current state: null
2025-06-12 10:53:20.841 29743-29743 CrashFailFastHandler    io....stant.companion.android.debug  E  	at io.homeassistant.companion.android.developer.DevPlaygroundActivityKt.DevPlayGroundScreen$lambda$14$lambda$13$lambda$12(DevPlaygroundActivity.kt:80)