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.