Forem: Adam McNeilly

Interface Naming Conventions

Adam McNeilly — Mon, 06 Feb 2023 01:20:25 +0000

Originally published on Android Essence.

Many engineers will tell you that one of the most complicated responsibilities of our job is naming things. Variables, classes, functions, everything we write requires conscious thought.

A special case among these are interfaces. This is because we not only have to name an interface, but we need to decide how to name the implementations as well.

Basic Convention

Traditionally, and by this I mean in the textbooks I read in college, interfaces and their implementations shared the same naming convention. I've seen this surfaced in one of two ways.

Using an IInterface and Implementation convention:

interface IBookRepository {
    // ...
}

class BookRepository {
    // ...
}

Using an Impl suffix:

interface BookRepository {
    // ...
}

class BookRepositoryImpl {
    // ...
}

Problems

This approach, while it does clearly separate the convention between an interface and its implementation, has a couple inherent problems.

It assumes one implementation per interface. If we write a BookRepository and BookRepositoryImpl, but need to add a second, different BookRepository what do we call it? BookRepositoryImpl2?
Similarly, the Impl suffix doesn't provide any information about how the implementation operates. Is it pulling local data? Remote data? What is the data source used by BookRepositoryImpl? All of these questions require active investigation and diving into the code to understand and come back with a confident answer.

Alternatives

To avoid these problems, we can consider a number of alternative naming conventions for our interfaces and their implementations. As always, we have multiple different solutions, that you may choose to stick to one, mix and match, or change based on your situation. I've decided to highlight a few different approaches I have tried myself, and have heard used by others. Have different ideas? Let me know in the comments!

Naming With Data Source

If our application has a BookRepository data source interface, the implementation can be named based on the data source used to request books. Some examples may look like this:

interface BookRepository

class GoogleBooksBookRepository : BookRepository

class OpenLibraryBooksRepository : BookRepository

class NewYorkTimesBookRepository : BookRepository

Naming With Situation

Sometimes, our implementation might always be specific to the same data source/dependency. We still may want to leverage interfaces because it helps with testing, or some other situation. In these moments, we can consider naming our interface based on the situation it is being used in. For example, consider we include some interface for Crashlytics initialization. In our production app, we can name it accordingly.

interface CrashlyticsInitializer

class ProdCrashlyticsInitializer : CrashlyticsInitializer

Why is this better than CrashlyticsInitializerImpl? I believe this is better because it begins to set a precedent for other situations we might use a CrashlyticsInitializer. Situations like our device tests, where we can have a TestCrashlyticsInitializer or a special debug flavor that includes a DebugCrashlyticsInitializer.

Naming With Responsibility

Another way to look at this is to think of the reponsibility of a class. Perhaps your repository combines other data sources, with an offline first preference. You may consider something like this:

interface BookRepository {
    // ...
}

class OfflineFirstBookRepository(
    private val localRepository: BookRepository,
    private val remoteRepository: BookRepository,
) : BookRepository { 
    // ...
}

Other Considerations

The above suggestions are my personal preference, but there are other situations you may want to consider. By prefixing the implementations, searching for them in the IDE becomes slightly less straight forward. When searching in Android Studio, for example, if we start typing BookRepository, any files that are named BookRepositoryImpl get included in the same search. For that reason, you may consider taking the above suggestions, and combining them with the traditional suffix, like this:

interface BookRepository

class BookRepositoryGoogleBooksImpl : BookRepository

class BookRepositoryOpenLibraryImpl : BookRepository

class BookRepositoryNewYorkTimesImpl : BookRepository

Recap

At the end of the day, the naming convention you and your team use is a personal choice. By using interfaces, we're making a good choice toward scalable applications. The naming convention is mostly cosmetic, but I hope you've seen that it can serve a purpose for discoverability and quickly understanding the codebase by reading class names. What I believe matters most is that you take the time to think about it. Your conversation may ultimately end with "well, there's no dependency or situation specific usage here, so we just want to fall back on the Impl suffix. That's okay! Not all suggestions apply to all situations, but hopefully this post helps you find ways to provide more clarity in class names.

The Imposter's Guide To Dependency Injection

Adam McNeilly — Sun, 30 Jan 2022 01:50:44 +0000

Dependency Injection is one of the hottest topics in Android and software development in general. It's also a topic that can provide a lot of anxiety and create imposter syndrome for developers.

In this post, we'll take incremental steps toward understanding DI, why we need it, and how to implement it inside our applications.

If interested, you can find this content in video form on YouTube:

It's also been published on Android Essence.

Code Without Dependency Injection

To start, let's review problems we might face if we write code without dependency injection. Consider the following code, where we have a ProfileViewModel class, and we want to track an event every time the user views a profile. This way we can see how common the screen is compared to others.

class ProfileViewModel() {

    fun onProfileLoaded() {
        Firebase.analytics.logEvent("viewed_profile")
    }
}

This code doesn't look like it causes any problems at first glance. In fact, if you look at the documentation for Firebase Analytics and similar tools, it will suggest writing code like this. So don't be ashamed if your codebase looks something like this. For code like this, there are two specific problems I'd lke to highlight:

Our code relies so heavily on Firebase Analytics, that if we wanted to change to another vendor we'd have to update every ViewModel in the application.
We will have difficulty writing tests for this piece of code.

Testing Difficulties

A good unit test to write for this piece of code is one that verifies when onProfileLoaded is called, that we also track the correct analytics event. If we start writing this test, though, we'll recognize a problem very quickly. How can we verify a call was made to Firebase?

class ProfileViewModelTest {

    @Test
    fun verifyEventTracked() {
        val viewModel = ProfileViewModel()
        viewModel.onProfileLoaded()

        // No Ability To Verify Event Tracked
    }

Not only that, this particular test will just crash. We'll get a RuntimeException that our main looper is not mocked, because of some work that's happening inside the Firebase Analytics library:

Caused by: java.lang.RuntimeException: Method getMainLooper in android.os.Looper not mocked.

Dependency Injection

Our code has a dependency on Firebase Analytics. We can help solve this testing problem by injecting it to the constructor:

class ProfileViewModel(
    private val analytics: FirebaseAnalytics = Firebase.analytics,
) {

    fun onProfileLoaded() {
        analytics.logEvent("viewed_profile")
    }
}

This approach is often referred to as "Constructor Injection", where dependencies are supplied via the constructor of a class. This is the core concept of dependency injection. Kelly Shuster summed it up well in her Tweet:

// Detect dark theme var iframe = document.getElementById('tweet-1020363593060093952-964'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1020363593060093952&theme=dark" }

DI has a complicated name for a concept that can be reduced down to "passing stuff in."

Updating Our Test

Now that we have a way to supply our dependency, we can update our test accordingly to provide a fake implementation of Firebase Analytics, that we can then use to verify the proper event was tracked:

class ProfileViewModelTest {

    @Test
    fun verifyEventTracked() {
        val mockAnalytics = FakeFirebaseAnalytics()
        val viewModel = ProfileViewModel(mockAnalytics)
        viewModel.onProfileLoaded()

        mockAnalytics.verifyEventLogged("viewed_profile")
    }
}

However, when we do something like this we should be considering the other problem discussed earlier. Despite injecting this dependency, we still have a strong reliance on Firebase Analytics. We should avoid this, so we can support the ability to provide a different analytics service in the future.

Wrapping Dependencies

We could create our own interface that defines an AnalyticsTracker, and a Firebase implementation of it. In the future, we can create other implementations for other services.

interface AnalyticsTracker {
    fun trackEvent(eventName: String)
}

class FirebaseAnalyticsTracker : AnalyticsTracker {
    override fun trackEvent(eventName: String) {
        Firebase.analytics.logEvent(eventName)
    }
}

Now we can have our ViewModel depend on this interface instead:

class ProfileViewModel(
    private val analytics: AnalyticsTracker = FirebaseAnalyticsTracker(),
)

Up until this point in the blog post, you've gained an understanding of the core concept of dependency injection, why we need it, and how to implement it for a given class. Having said that, let's address a new question:

Why does dependency injection seem so much more complicated than passing stuff in?

There are a few advanced topics of dependency injection, starting with the idea of sharing dependencies. We can continue with our analytics tracking example. Analytics are everywhere, so we want to be able to provide one instance of an analytics tracker to be used by each screen. We also want to create a setup so that we can make one change to have every screen updated accordingly.

Dependency Injection Recipe

To achieve this goal, we can follow three steps.

Create a container to hold the dependencies used in our application.
Modify our Application class to be the host of those dependencies.
Update our individual screens to request those dependencies.

To implement the first step, we can create a class called AppDependencies. Notice how our analytics tracker is typed to the interface from earlier, but will return a Firebase implementation:

class AppDependencies {
    val analyticsTracker: AnalyticsTracker
        get() = FirebaseAnalyticsTracker()
}

Next, we can create a reference to this dependency container inside our Application class:

class MyApp : Application() {
    val appDependencies = AppDependencies()
}

Lastly, we can get a reference to our Application Context from within an Activity or Fragment to request the dependencies:

class ProfileActivity : Activity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        val appDependencies = (this.application as MyApp).appDependencies
        val analyticsTracker = appDependencies.analyticsTracker
        val profileViewModel = ProfileViewModel(analyticsTracker)
    }
}

You can learn more about manual dependency injection from this Android guide.

Dependency Injection Libraries

Every few months a flamewar emerges on Android Twitter about which dependency injection library people should use. This only contributes to the confusion and anxiety people face when discussing dependency injection, which is why discussing them has been saved for the end of this post. DI libraries exist to help reduce some of the boilerplate code of a manual approach, but they actually follow the same recipe: create a group of dependencies, store them in your Application class, create a mechanism for requesting those dependencies.

Let's look briefly at two dependency injection libraries and how they achieve this.

Hilt

Hilt is the official recommendation from Google for a dependency injection library. It manages dependencies through annotation processing. I recommend viewing the official docs to learn more, but let's review how Hilt uses our DI recipe.

First, we can create a Module in Hilt that defines a group of dependencies. Here is an example module - don't be scared about all the annotations. The key point here is that we have a way to create an instance of AnalyticsTracker of type FirebaseAnalyticsTracker:

@Module
@InstallIn(ActivityComponent::class)
abstract class AnalyticsModule {

  @Binds
  abstract fun bindAnalyticsTracker(
    analyticsTracker: FirebaseAnalyticsTracker
  ): AnalyticsTracker
}

Next, we can setup our Application class. Hilt makes this incredibly easy, we just need to use the @HiltAndroidApp annotation:

@HiltAndroidApp
class MyApp : Application()

Last, we need a mechanism for requesting dependencies. With Hilt, we just use the @Inject annotation:

@AndroidEntryPoint
class ProfileActivity : Activity() {

    @Inject 
    lateinit var analytics: AnalyticsTracker
}

Koin

Another common DI library is Koin. While the syntax and technical implementations are different, we once again see the same recipe used.

Create a collection of dependencies:

val analyticsModule = module {
    single<AnalyticsTracker> {
        FirebaseAnalyticsTracker()
    }
}

Store them in your Application class:

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()

        startKoin {
            modules(analyticsModule)
        }
    }
}

Request them in your Activity:

class ProfileActivity : Activity() {

    val analytics: AnalyticsTracker by inject()
}

We're not going to dive into the nuanced differences between Hilt and Koin today. Instead, I just wanted to provide an overview of the libraries and show that they follow the same steps as writing our own manual dependency injection.

Recap

The dependency injection library you choose (or don't) matters so much less than why we need dependency injection in the first place. In this post, we reviewed how dependency injection enables better testing in our codebase, the ability to swap out dependencies for any reason in the future, and provides us with a centralized location to manage all of our applications dependencies.

Did this help ease some of your anxiety around this complicated topic? Let me know in the comments, as well as any other imposter-syndrome-inducing topics we should look at in the future.

Creating A Better Developer Experience By Avoiding Legacy Code

Adam McNeilly — Fri, 09 Oct 2020 17:41:45 +0000

Legacy code is an unfortunate thing for any software developer to inherit. It's something many of us have worried about in our careers, and will probably continue to worry about. Throughout this post, we'll understand what legacy code is, what causes it, and how we can work to avoid it. Doing so will help us create a better developer experience for ourselves, and our future teammates.

This is an adaptation of a presentation I gave at Android Summit 2020. You can find the slides here.

What Is Legacy Code?

There are many different ways to define and interpret legacy code, so let's define a baseline understanding of what we mean for the intents and purposes of this post.

Code that was written before we knew better - new tools and practices exist now.
Code that was written by someone else who left our team - taking institutional knowledge with them when they left.
Code that doesn't have any unit test coverage.
Code that we're unable to/afraid to change because we don't know what might break.
Code without any type of documentation or comments.
All of the above!

None of these bullet points are mutually exclusive. When we refer to legacy code, it could be code that is one or all of these things.

Why Do We Care?

Why are we even taking time to discuss legacy code today? We need to understand legacy code because it impacts our work. Let's discuss how it does that.

Legacy Code Can Be A Blocker For New Development

If you have code that no one understands, or is tightly coupled to some third party tool, and you need to make changes or build on top of it - it's hard to do so! Which means you have to have a difficult conversation with your project manager about whether or not you can implement a new feature.

Legacy Code Can Prevent Us From Shipping With Confidence

If code is old, unclear, undocumented, and untested it will be hard to sleep at night when we ship changes to this code. If we can't have confidence in the changes we make, all releases will be more stressful than they otherwise would be.

Legacy Code Is Not Fun To Work With

For these and many other reasons, legacy code is just not fun to work with. Maybe you have a piece of code in your project that whenever you're asked to do development related to it, you automatically get nervous. This shouldn't happen! Code can be difficult, but we want this to be a pleasant experience as much as we can. So studying legacy code and avoiding it can help us create that pleasant experience.

Exploring Causes Of Legacy Code

Now that we understand what it is, and the problems it creates for us, let's look at some causes of legacy code.

Legacy Code Doesn't Have Tests

If you're not writing sufficient unit tests for your code, it is bound to become legacy code. This may not seem intuitive at first - we could have amazing code that is simply untested. However, as Jorge Coca points out, untested code becomes code that we're afraid to change:

// Detect dark theme var iframe = document.getElementById('tweet-1313883297177645064-656'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1313883297177645064&theme=dark" }

There are ultimately two reasons that code doesn't have tests.

The developer chose not to write any - this can happen for a number of reasons.
The code wasn't testable in the first place - making writing tests impossible.

The latter is a big red flag for other legacy code concerns, so let's look at what this means.

Untestable Code

Untestable code is usually code that has a lot of static references. References to global singletons that exist outside of our project that could be manipulating some global state that our tests aren't prepared to handle.

It can also refer to code that doesn't leverage proper dependency injection, meaning our class relies on dependencies that are hard to mock inside of our unit tests. This means we will have difficulty writing tests that can truly run in isolation.

Let's consider this example of untestable code. We've got a ProfileViewModel that tries to load a user's profile information, and if the network request fails, it will log that information in our Firebase dashboard.

class ProfileViewModel : ViewModel() {
    private fun loadProfile() {
        try {
            // ...
        } catch (e: Throwable) {
            Firebase.getInstance().logException(e)
        }
    }
}

Please keep in mind this issue is not specific to Firebase, but we've chosen to reference a common error reporting tool to help readability.

There's a few reasons this code is difficult to test:

Firebase.getInstance() is not a method we have control over, so it is difficult to provide a mock implementation of Firebase for our unit tests.
We don't want our negative tests to actually record errors to our production Firebase tool. That would just create noise in our dashboard.
The Firebase setup could be doing some work that our unit tests aren't prepared to handle, and could end up crashing our unit tests.

Untestable Code - Quick Solution

There is a quick solution to this problem, which is that instead of referencing a static Firebase instance, we can inject that instance into our ProfileViewModel using a constructor parameter:

class ProfileViewModel(
    private val firebase: Firebase = Firebase.getInstance()
) : ViewModel() {
    private fun loadProfile() {
        try {
            // ...
        } catch (e: Throwable) {
            firebase.logException(e)
        }
    }
}

This solves some of our testability problems. We now have the freedom to create our own mock Firebase implementation, and use that during our unit tests. However, this code is about to lead us into another common legacy code problem.

Tightly Coupled Dependencies Become Legacy Code

Companies change third party vendors all the time (different error reporting tools, different analytics trackers). They may also change tech stacks - REST APIs to GraphQL, for example.

Code that doesn't allow these things to change is likely to become legacy code, because it prevents those business decisions from happening easily.

Tightly Coupled Dependencies

Let's dissect this constructor parameter here:

class ProfileViewModel(
    private val firebase: Firebase = Firebase.getInstance()
) : ViewModel()

Despite dependency injection, this class is still tightly coupled to the Firebase error reporting tool. This means that as Firebase changes, this class may need to change with it. If our company wants to move from Firebase to Sentry, or Embrace, we will have difficulty doing so because these tools may have completely different method signatures for logging errors.

Wrapping Dependencies

The solution to this problem is to wrap all of our third party dependencies. We do that by creating interfaces that define the expected behavior of the tools:

interface ErrorReporter {
    fun reportError(error: Throwable)
}

We can then create our own implementation of this interface, that we can tightly couple to a third party tool:

class FirebaseErrorReporter : ErrorReporter {
    override fun reportError(error: Throwable) {
        Firebase.getInstance().logException(error)
    }
}

As a result, we can update our ViewModel to instead rely on the ErrorReporter interface. Thanks to Kotlin's default arguments, we can still make Firebase our default tool - but ultimately the ViewModel no longer has any strict knowledge of Firebase itself.

class ProfileViewModel(
    private val errorReporter: ErrorReporter = FirebaseErrorReporter()
) : ViewModel()

This gives us three big benefits:

It is now easier to provide fake/mock implementations in our unit tests because we can implement the interface ourself.
It becomes easier to entirely swap third party tools.
It becomes easier to update our third party tools.

To provide an example for the second and third points, let's consider a global dependency injection manager that creates the ErrorReporter used in the application. If this is created in one single place, that means if we ever created a different ErrorReporter, we would only have to update that one line to update the whole project!

/**
 * Change the reporter supplied by your DI manager,
 * the entire app just updates!
 */
single<ErrorReporter> {
    FirebaseErrorReporter()
    // SentryErrorReporter()
    // EmbraceErrorReporter()
}

Similarly, if for any reason the third party tool changes something about their method signature, we can handle that directly in our implementation class, without having to update the whole project:

class FirebaseErrorReporter : ErrorReporter {
    /**
     * Wrapping this method makes it easy to update our project
     * if the library changes its method signature.
     */
    override fun reportError(error: Throwable) {
        // Firebase.getInstance().logException(error)
        Firebase.getInstance().logError(error)
    }
}

These Steps Avoid A Lot Of Legacy Code Pain Points

There's a lot more to discuss about wrapping dependencies and writing testable code, but the two steps we've discussed here (dependency injection and wrapping dependencies) will take us very far:

We have testable code we can ship with confidence.
We have decoupled third party tools, giving us the freedom to swap them with ease.
We can confidently upgrade our third party tools and limit code changes required.

Now we'll look at one more cause of legacy code.

Legacy Code Doesn't Have Documentation

There is a lot that goes into writing good code comments, but code without any is likely to become legacy code.

This process happens because a developer may write code that they understand, and is understood by the code reviewer at the time. If there is some external knowledge used in writing that code though, it may not become clear to future teammates who have to inherit that code and they will end up unsure how it works, why it works, or if it can be changed.

Looking After Each Other With Documentation

When we write documentation, we don't write it for ourselves today. We write it for our future teammates who will see that code later. We should be thinking about them when we write our documentation to help them as much as possible.

Document When And Why You Rely On External Code Samples

If you include code that you've found on StackOverflow to solve a problem, it can be very helpful to document why you did that and where it came from. This helps solve a few problems:

It lets your future teammates know why this code was added, and allows them to explore if new first party solutions exist.
It can tell your future teammates where the source code came from, so they have a place to go with questions if they need to.

Here's an example of a helpful comment for this situation:

/**
 * Feature XYZ requires a ViewPager like experience, but
 * without the user being able to control each step. We've
 * implemented a ViewPager that rejects any user interraction.
 *
 * Source: https://stackoverflow.com/a/9650884/3131147
 */
class NonSwipeableViewPager(
    context: Context, 
    attrs: AttributeSet? = null
) : ViewPager(context, attrs) {
}

Document When You Work Around Library Bugs

Let's look at a very helpful example of writing a comment when you work around a bug in a third party tool:

/**
 * Due to github.com/company/library/issues/1234 we needed
 * to implement this work around to prevent a crash on
 * Android devices running API 21.
 */
private fun doLibraryWorkAround() {
    // ...
}

This comment helps your future teammates for a couple key reasons:

It provides a link to the bug you are working around. This allows them to see if a new library update exists now that can replace this code.
It gives a specific example of who was impacted by this work around, so they know what to test when they update the library.

Document Why You Use Third Party Libraries

Take this piece of advice with a grain of salt. Sometimes your project will rely on industry standard dependencies that we can expect people to understand. Other times, we may be using a tool for one specific scenario, and it can save our future teammates time by explaining why:

implementation("com.jakewharton:process-phoenix:$rootProject.ext.versions.phoenix") {
    because("We use ProcessPhoenix to programmatically restart the application when network settings are changed.")
}

Why This Documentation Matters

This wasn't an exhaustive list of helpful documentation, but it can make a big difference. We're not trying to prevent code from becoming obsolete and outdated. We're trying to help the future maintainers respond accordingly.

Recap

Writing testable code with decent coverage helps future developers refactor with confidence.
Wrapping dependencies allows future developers to update and replace tooling easily.
Documenting certain decisions allows future developers to confident understand, refactor, and replace code written by someone else.

Remember

The goal isn't to completely eradicate legacy code. The goal is to look out for our future teammates by not leaving behind rigid, confusing, and unmaintainable code.

I hope you learned some helpful tips and tricks from this post to avoid common legacy code problems. If you have any questions, or other ideas to avoid legacy code, let me know on Twitter or in the comments!

MVWTF: Demystifying Architecture Patterns

Adam McNeilly — Fri, 16 Aug 2019 19:10:23 +0000

Originally published on Android Essence.

You can watch this talk from Android Summit on YouTube:

As an Android developer, one of the questions I constantly see asked within the community is "what architecture pattern should I use?"

This discussion usually leads to a handful of buzzwordy acronyms:

MVC
MVP
MVVM
MVI
MVU?? (We don't talk about this but apparently it's the new kid on the block)

This can be really intimidating to new Android devs, as well as seasoned veterans who are constantly questioning if they're using the right one. Whether you're trying to decide which one to learn, or wondering if the one you already use is best for you, this post will help lead you to the right decision.

We should first start off by understanding why we even need architecture patterns. When that question is asked, we get even more buzzwords, saying we want code that is:

Maintainable
Extensible
Robust
Testable

At face value, these may not sound like buzzwords, but are often just filler. What does it mean to write maintainable code anyways? The word robust means strong and healthy. What is strong and healthy code?

We're going to start at the beginning. Putting all of the buzzwords aside, we need to start with one single truth that is the basis for the rest of this post:

You can't put all of your code in the Activity.

Implicitly we all know this, and we put our code into separate files. However, it's more than just putting various classes into their own file. How we decide to break apart our code is very important, and that process is what architecture patterns are for. An architecture pattern is the way of describing how you split up your code.

Let's work through some options we have for splitting up our code by tackling the list of acronyms from the beginning, starting at the top.

Model-View-Controller

MVC deserves a quick section simply because it's one of the oldest architecture patterns. It was developed in the 1970s as a way to break up your application into three components: a model, a view, and a controller. It's important to understand the function of each component.

Model

The model component is your data source. This can be a database, remote server, local text file, or anything else. The important thing to remember is that it does not care about the view.

Your model should not be responsible for any behavior related to how data is displayed, just retrieving it.

For example, if you want to fetch a user and display a label that has the username and age together, you will create that label elsewhere. Not inside the model component.

View

The view component is the visual representation of your data. That is all it is responsible for. It should not care where that data came from. The view should not be making any decisions. If you find yourself writing a conditional logic in your view component, consider refactoring that.

Controller

Being the last component, the controller is responsible for just about everything else. It should:

Handle user input
Validate that input if necessary
Pass that input into the model
Pass that model response into the view

An easy way to think about this flow is to consider a form. The controller reads all of your text inputs, makes sure you've filled everything out, sends it to the model, and then tells the UI to show a success screen.

MVC Diagram

Let's take a look at how this all connects together:

Why Don't We Use This On Android?

At face value, this looks pretty good. Our concerns are separated and the flow of information is pretty clear.

However, of all the patterns in this post, MVC is the one discussed the least on Android. There's a quick explanation for this.

When you consider the responsibilities of a controller (accepting user inputs) and the responsibility of a view (displaying data), you may recognize that these are handled by the same thing in Android. This is your Activity or Fragment.

Why Is This Bad?

I'd like to highlight two reasons we wouldn't want this on Android:

We can't write Junit tests for an Activity or Fragment, so we should move as much code out of there as we can.
Our concerns aren't actually separated if two of three components are in the same class.

How Do We Fix This?

Let's move the controller/UI logic out of the Activity/Fragment.

Model-View-Presenter

By breaking the UI and business logic out of the Activity/Fragment, we create a slightly different flow of information. This creates the MVP pattern.

Now we have a separation of concerns where all of our non UI code is outside of the Activity/Fragment, and we can unit test all of it.

MVP Implementation

Before we move on to the next pattern, I think it's important to understand a little bit about the implementation of a pattern like MVP, so we can compare how the code evolves along the way, too.

Contract Class

The first thing we need to do to build a feature in MVP is design a contract class that has the interfaces defining the behavior of our three components:

class TaskListContract {

    interface View {
        fun showTasks(tasks: List<Task>)
    }

    interface Presenter {
        fun viewCreated()
        fun viewDestroyed()
    }

    interface Model {
        fun getTasks(): List<Task>
    }
}

Model

Our model can be a simple in memory list for this example.

Notice that our model doesn't actually reference other components.

class InMemoryTaskService : TaskListContract.Model {
    override fun getTasks(): List<Task> {
        return listOf(...)
    }
}

View

The view really only needs to do two things here:

Notify the presenter of any relevant life cycle methods, or click listeners if that was relevant
Override any methods from our contract class to display data

Notice that our View only has a reference to the Presenter.

class TaskListActivity : AppCompatActivity(), TaskListContract.View {
    private val presenter = TaskListPresenter(this, TaskRepository())

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...

        presenter.viewCreated()
    }

    override fun onDestroy() {
        presenter.viewDestroyed()
        super.onDestroy()
    }

    override fun showTasks(tasks: List<Task>) {
        taskAdapter.tasks = tasks
    }
}

Presenter

The presenter needs to override the methods from the contract class, call the view when necessary, and do any clean up required to avoid memory leaks (like removing a reference to the view).

Notice that our presenter has both a reference to the View, and a reference to the Model.

class TaskListPresenter(
        private var view: TaskListContract.View?,
        private val model: TaskListContract.Model
) : TaskListContract.Presenter {

    override fun viewCreated() {
        val tasks = model.getTasks()
        view?.showTasks(tasks)
    }

    override fun viewDestroyed() {
        view = null
    }
}

Is This Good Enough?

Our view is only responsible for displaying data
Our model handles fetching data
The presenter handles all inputs and UI logic
Everything is well separated and everything is testable
If you think this is good enough, use it!

What Is Different About MVVM?

Each architecture pattern in our original list leads into the next. MVP serves as a base for our discussion about MVVM, because there's really only one nuanced difference between them: the presenter doesn't need to care about the view.

Model-View-ViewModel

In the last pattern, we see that the presenter explicitly tells the view what to display. As an alternative, we can consider an event based approach where we just expose the state that our view should be in and anyone who needs to display that state can subscribe to those changes.

That's exactly how MVVM works. It breaks the connection between the presenter and the view and instead exposes information via some observable type, like LiveData or RxJava.

MVVM Implementation

Let's look at the code comparisons between implementing MVP and MVVM.

Model

The model component doesn't actually change much. Since we no longer have a contract class, though, I still recommend setting up an interface for your data fetching behavior.

interface TaskRepository {
    fun getTasks(): List<Task>
}

class InMemoryTaskService : TaskRepository {

    override fun getTasks(): List<Task> {
        return listOf(...)
    }
}

View

The view behaves similarly to the last example, in that we need to:

Create a reference to our ViewModel
Observe changes from that ViewModel to update the UI accordingly

class TaskListActivity : AppCompatActivity() {
    private val viewModel = TaskListviewModel(repository = InMemoryTaskService())

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // ...

        subscribeToViewModel()
    }

    private fun subscribeToViewModel() {
        viewModel.getTasks().observe(this, Observer { tasks ->
            adapter.tasks = tasks
        })
    }
}

ViewModel

Our ViewModel will look similar to the presenter, with a few key differences:

We no longer have a reference to the view, only the model component
We expose information via a LiveData object
We can fetch information as soon as we initialize, so we don't need to be notified of view creation

class TaskListViewModel(
        private val repository: TaskRepository
) {
    private val tasks = MutableLiveData<List<Task>>()
    fun getTasks(): LiveData<List<Task>> = tasks

    init {
        fetchTasks()
    }

    private fun fetchTasks() {
        tasks.value = repository.getTasks()
    }
}

What Makes MVVM Better Than MVP?

Up to this point, our code looks exactly like it did before, minus a direct reference to the view. The benefit of dropping that connection is that now we can leverage Android's ViewModel architecture component to help handle configuration changes better.

In MVP, our presenter had a reference to the view, which is often an Activity. If I rotate my phone, that activity is recreated, and now the presenter is referencing an Activity that no longer exists.

With a ViewModel, we have something that outlasts those configuration changes, and never has to lose state.

Handle Rotation in MVP

In MVP, we had to follow a lot of steps to handle rotation:

Add two new methods to our presenters contract to getState() and restoreState()
Update our view to call those methods in the corresponding lifecycle steps
Implement the methods to retrieve state and restore it in the presenter

Depending on how complicated your state is, step 3 can take a lot of time and require a lot of code.

Handle Rotation In MVVM

To make sure we easily handle rotation in MVVM, we do the following:

Update our ViewModel to extend the Android ViewModel architecture component
In our Activity, use ViewModelProviders to get the ViewModel that already exists
Re-subscribe to the LiveData to get the state

The first two steps are the same level of effort as those in the previous section, but now we don't have to think about saving and restoring state. We just need to re-subscribe to LiveData.

This saves us A LOT of time.

If you want to see the code comparisons there, please check out the slides from when this was post was given as a presentation.

Why Isn't MVVM Good Enough?

As we work through these architecture patterns, each one sounds even better. Now we have all the separation and testability benefits of MVP, and we have better state management on rotation!

There's still one more acronym in our list, though, which spoils the fun that MVVM isn't the best we can do. To understand where it falls short, let's look at a more complicated state.

Consider a feature that fetches a list of tasks and supports both a loading and an error state. You may try to put your state into some Kotlin sealed class:

sealed class TaskListState {
    object Loading : TaskListState()
    data class Loaded(val tasks: List<Task>) : TaskListState()
    data class Error(val error: Throwable?) : TaskListState()
}

Next, you update your ViewModel to show the state according to what's happening:

class TaskListViewModel(private val repository: TaskRepository) : ViewModel() {

    init {
        showLoading()
        try {
            fetchTasks()
        } catch (e: Exception) {
            showError()
        }
    }

    private fun showLoading() {
        state.value = TaskListState.Loading
    }

    private fun fetchTasks() {
        val tasks = repository.getItems()
        state.value = TaskListState.Loaded(tasks)
    }

    private fun showError() {
        state.value = TaskListState.Error(Throwable("Unable to fetch tasks."))
    }
}

This looks pretty good. There are some risks to the showLoading(), fetchTasks(), and showError() methods, though.

Any methods in the class can call them
We can't guarantee they're associated with a specific action or intent
We have multiple methods manipulating our state that we have to ensure don't conflict with each other

For a simple example like this one, MVVM may be fine. I can easily test everything to ensure I call these methods in the right order and avoid those risks. However, they would become more prevalent as our ViewModel gets more complicated. The next pattern works to solve that.

Model-View-Intent

Unlike the previous patterns, "Intent" doesn't refer to some specific component, but rather the intention of doing something that we want to capture in our state.

Managing Predictable State Changes With A Reducer

The first problem with MVVM that we can tackle is the lack of predictable state changes. Instead of having multiple methods that manipulate our state, we should have one pipeline. This flow will take in some action, and a current state, and output a new state for us.

Here is what that method signature would look like:

abstract class Reducer {
    abstract fun reduce(action: Action, state: State): State
}

If you are using a sealed class like we saw earlier to represent your state, we can have very clearly defined inputs and outputs:

class TaskListReducer : Reducer<TaskListState>() {

    override fun reduce(action: Action, state: TaskListState): TaskListState {
        return when (action) {
            is TaskListAction.TasksLoading -> TaskListState.Loading()
            is TaskListAction.TasksLoaded -> TaskListState.Loaded(action.tasks)
            is TaskListAction.TasksErrored -> TaskListState.Error()
            else -> state
        }
    }
}

If you're not using sealed classes, we can also leverage the copy() methods from data classes to handle updating our state here as well:

class TaskListReducer : Reducer<TaskListState>() {

    override fun reduce(action: BaseAction, state: TaskListState): TaskListState {
        return when (action) {
            is TaskListAction.TasksLoading -> state.copy(
                isLoading = true,
                isError = false,
                tasks = null
            )
            is TaskListAction.TasksLoaded -> state.copy(
                isLoading = false,
                isError = false,
                tasks = action.tasks
            )
            is TaskListAction.TasksErrored -> state.copy(
                isLoading = false,
                isError = true,
                tasks = null
            )
            else -> state
        }
    }
}

Using A Store For A Single Source Of Truth

The other goal we want to accomplish with MVI is to have a single source of truth for our state. We can achieve this by creating a state container called a Store. It has the following responsibilities:

The store maintains the reference to our current state
The store holds the reference to our reducer
The store is responsible for dispatching actions into the reducer to update the state

Here's a quick snippet on how we can implement all of that. In this example I expose the state via some listener that gets called whenever it changes, but you can do this with RxJava, LiveData, etc.

class BaseStore<S : State>(
    initialState: S,
    private val reducer: Reducer<S>
) {
    private var stateListener: ((S) -> Unit)? = null

    private var currentState: S = initialState
        set(value) {
            field = value
            stateListener?.invoke(value)
        }

    fun dispatch(action: Action) {
        currentState = reducer.reduce(action, currentState)
    }

    fun subscribe(stateListener: ((S) -> Unit)?) {
        this.stateListener = stateListener
    }
}

This is better than what we had previously, because the state lives in one place only (the store) and can only be modified by one thing (the reducer). Not only do we get clearly defined inputs and outputs from this, but we are also able to get a unidirectional flow of data, as seen in this diagram from Esri:

Connect This To Our ViewModel Or Presenter

Note in the diagram that we have a component that dispatches actions. This can be anything, meaning you don't need to be using MVVM to implement this flow. You can create a store and reducer and plug them into a presenter, too!

For this post, we'll hook it up to a ViewModel. All we need to do is create a reference to the store, and where we were previously modifying state we will just dispatch actions to it:

class TaskListViewModel(private val repository: TaskRepository) : ViewModel() {
    private val store: BaseStore<TaskListState> = BaseStore(
        TaskListState.Loading(),
        TaskListReducer()
    )

    // ...

    private fun fetchTasks() {
        store.dispatch(TaskListAction.TasksLoading)

        try {
            val tasks = repository.getTasks()
            store.dispatch(TaskListAction.TasksLoaded(tasks))
        } catch (e: Throwable) {
            store.dispatch(TaskListAction.TasksErrored(e))
        }
    }
}

Recap

Wow! That was a lot to take in, and thanks for making it this far. Let's TL;DR everything we just saw:

MVP is helpful because it separates our concerns and gives us code that is all junit testable. However, state management is unpredictable and rotation requires more work to support.

MVVM is a step forward, because we break the two way communication between the View and the Presenter allowing for better rotation support, but we still have unpredictable state management.

MVI takes us even further, by giving us predictable state management with clearly defined inputs and outputs.

So What Should I Use?

While it is clear that MVI is the strongest pattern we discussed, it's not always right for everyone. If your feature is really complex and has confusing user flows, you can benefit a lot from having that predictable state management.

If your feature is simply fetching and displaying some data, though, the learning curve of MVI and extra code required might not be worth the effort. It's up to you as a developer to decide how much complexity you need.

You certainly shouldn't feel bad about using MVVM, and in fact in the majority of features I've built it works well for me.

Code Samples

Interested in seeing the implementation for a specific pattern? Check out this GitHub repository which has a sample app with a module for each architecture pattern.

If you have any questions, drop a comment below or reach out to me on Twitter! If you were inspired by any particular section and want to see a deeper dive into a specific pattern, let me know!

//TODO: Write a better comment

Adam McNeilly — Thu, 13 Jun 2019 13:53:48 +0000

This was presented at Droidcon NYC 2019. See the video here:

Earlier this month, there was a very controversial tweet by the official Java Twitter account, telling you to stop writing code comments.

// Detect dark theme var iframe = document.getElementById('tweet-1135222291007062021-867'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1135222291007062021&theme=dark" }

It links to a Medium article which explains some of the problems with code comments and suggests the solution is to stop writing them entirely.

This is bad advice. I was shocked to see it come from the official social media account of such a popular programming language. Code comments can provide a lot of value to your code base and really help the next person who inherits your code. I also found the article to be unnecessarily harsh:

When you need to write a comment, it usually means that you have failed to write code that was expressive enough. You should feel a sharp pain in your stomach every time you write a comment.

I'm here to tell you that you are not a failure for writing comments. Nor that you should feel guilty for doing so. As a community, we shouldn't stop writing comments. We need to learn to write better comments. I'm hoping this will serve as a guide to help you do that.

The Risk Comments Pose

First, let's define a baseline understanding of the benefits comments bring us, but also the risks.

Comments are helpful because they can provide insight to the readers of your code that the code itself may not be able to.

Comments are a potential risk because they can become outdated. Changing the code doesn't guarantee we change the comments, and thus we could have comments that mislead us. That is why, by default, we should try to avoid comments.

However, we shouldn't avoid comments just for avoidance sake. We should make sure we're intentional about the comments we do - and don't - write.

In my experience, the code comments I've come across can be grouped into three buckets:

This comment is unnecessary.
This comment is unhelpful.
This comment is helpful.

The goal is to make sure all of the comments we have are in the third bucket - helpful. We can start by removing any unnecessary comments, and then ensuring the remaining comments are helpful to the reader.

Avoiding Unnecessary Comments

Some code comments are just not needed. In these cases, we should just get rid of them. Otherwise there is more clutter in our files, and more risk of comments becoming out of date and actually going from unnecessary to unhelpful.

Remove Redundant Comments

The first type of unnecessary comment we can remove is a redundant one.

You may feel the urge to document a method and all of its params, but sometimes your code is so expressive it's hard to write a unique comment. That can lead you to something like this:



interface AccountDAO {
    /**
     * Inserts an account into the database.
     *
     * @param[account] The account that we're inserting.
     * @return The ID of the inserted account.
     */
    suspend fun insert(account: Account): Long
}

The documentation on the insert method isn't all that necessary. The first line provides a little info, but given the method name and the interface it belongs to one can deduce what it does. The explanation of the account parameter is again repeating something the code already tells me. The return statement, however, can provide some benefit.

So 2/3 of this comment is providing me with information that the code already provides me. That means it's redundant. I think that no comment is better than a redundant comment, because it doesn't put us at risk of having an outdated comment. So I would recommend only including the beneficial part:



interface AccountDAO {
    /**
     * @return The ID of the inserted account.
     */
    suspend fun insert(account: Account): Long
}

An Exception

An exception to this rule is if you are building a public API or library for others to use. In this scenario, you should document everything that is available. Even still, we can be thoughtful about the comments we write and ensure that they are helpful, which we'll discuss later.

Change Code To Avoid Needing A Comment

Let's continue with the baseline goal to avoid comments. You've started writing one, and you've made sure it's not redundant. Next, you should see if you can rewrite the code to make this comment unnecessary, so that you can remove it.

Here is an example of a short one line comment that helps clarify what a method may do:



// Saves data to database
fun saveData() {
}

The author of this comment (spoiler: me) felt that comment helped clarify what the method was doing. In hindsight, I could avoid this comment entirely by just making a more expressive method name:



fun saveDataToDatabase() {
}

Another common example of this is when we write a method that does multiple things, and we want to break out the parts of that method, like this:



fun transferMoney(fromAccount: Account, toAccount: Account, amount: Double) {
   // create withdrawal transaction and remove from fromAccount
   // ...

   // create deposit transaction and add from toAccount
   // ...
}

Putting aside that having one method do multiple things breaks other best practices, this leads us to extra comments that we'd like to avoid. One way to avoid them is to just put the steps into their own methods that are appropriately named.



fun transferMoney(fromAccount: Account, toAccount: Account, amount: Double) {
   withdrawMoney(fromAccount, amount)
   depositMoney(toAccount, amount)
}

Writing Helpful Comments

If you've gone through the last section, and you still feel you should include your comment either because it is a public API or because you feel it provides additional value, we need to ask ourselves if it's going to be helpful to the reader.

Comments Tell You Why, Code Tells You What

I cannot remember where I first heard this quote, but it has always resonated with me. The code should tell you what is happening, but the comments can tell you why.

Let's look at a bad comment that I wrote recently, one that repeats the what:



/**
 * A list of updated questions to be replaced in our list by an interceptor.
 */
private val updatedQuestions: MutableMap<Long, Question> = HashMap()

This comment is almost helpful, but I have to put it in the unhelpful category. It provides me a little extra info, but largely repeats what code can already tell me. In the last section we said we should remove these, but the story behind this one is that I actually want to provide insight into why I added this HashMap.

Let's turn this comment into a helpful one, by focusing on why:



/**
 * The `PagedList` class from Android is backed by an immutable list. However, if the user answers
 * a question locally, we want to update the display without having to fetch the data from the network again.
 * 
 * To do that, we keep this local cache of questions that the user has answered during this app session,
 * and later when we are building the list we can override questions with one from this list, if it exists,
 * which is determined based on the key of this HashMap which is the question ID. 
 */
private val updatedQuestions: MutableMap<Long, Question> = HashMap()

Now we have a comment that actually provides some insight into why I'm keeping a local HashMap, which is because I want to override an immutable list that I can't easily modify (thanks, Android). As a result, we have a helpful comment.

Comments With Examples Are Helpful

We keep mentioning that redundant comments should be avoided. A case where that is difficult is when we're creating a public API for others to use, and we want to make sure everything is documented. That poses a risk of some repetitive info. Here's another example:



class Pokedex {
    /**
     * Adds a pokemon to this Pokedex.
     * 
     * @param[name] The name of the Pokemon.
     * @param[number] The number of the Pokemon.
     */
    fun addPokemon(name: String, number: Int) {

    }
}

If we have to keep these comments, we can do our best to make sure they're helpful. One way to do that, if you can't provide additional info, is to provide examples:



class Pokedex {
    /**
     * Adds a pokemon to this Pokedex.
     * 
     * @param[name] The name of the Pokemon (Bulbasaur, Ivysaur, Venusaur).
     * @param[number] The number of the Pokemon (001, 002, 003).
     */
    fun addPokemon(name: String, number: Int) {

    }
}

This isn't drastically better, but rather than repeating information for our readers, we've now given them an example of what is expected.

Links To External Resources Can Be Helpful

We've all found solutions to our problems on StackOverflow. Sometimes that's an easy thing we can copy and paste into our project, but sometimes it might be a whole file or method that we reuse. In this case, it might be confusing to the reader where this code or concept came from, or why it's needed.

You can provide those insights by linking to the appropriate question or answer. Recently I created a programmatic ViewPager thanks to StackOverflow, and I wanted to give credit and make sure I had something to reference for more info, if the ViewPager ever had any issues:



/**
 * A ViewPager that cannot be swiped by the user, but only controlled programatically.
 *
 * Inspiration: https://stackoverflow.com/a/9650884/3131147
 */
class NonSwipeableViewPager(context: Context, attrs: AttributeSet? = null) : ViewPager(context, attrs) {
}

Actionable Comments Are Good Comments

This might come as a shock, as comments are not usually presented as something that should be actionable. Actionable comments are helpful because you give the reader something to take away, preventing them from asking "what am I supposed to do with this information?"

There's two types of comments I think we can focus on as being actionable.

TODO Comments

In general, TODO comments are a big risk. We may see something that we want to do later so we drop a quick //TODO: Replace this method thinking we'll come back to it but never do.

If you're going to write a TODO comment, you should do one of two things:
1) Just Do It™
2) Link to your external issue tracker.

There are valid use cases for a TODO comment. Perhaps you're working on a big feature and you want to make a pull request that only fixes part of it. You also want to call out some refactoring that still needs to be done, but that you'll fix in another PR. Link to something that holds you accountable, like a JIRA ticket:



//TODO: Consolidate both of these classes. AND-123

This is actionable because it forces us to go to our issue tracker and create a ticket. That is less likely to get lost than a code comment that will potentially never be seen again.

Deprecation Comments

Another time comments can be actionable is if you're leaving a comment around a method or class that you've deprecated and you want to tell the user where to go next.

I lifted an example of this straight from Android, where they deprecated CoordinatorLayout.Behavior in favor of CoordinatorLayout.AttachedBehavior:



/**
 * ...
 * @deprecated Use {@link AttachedBehavior} instead
 */
@Deprecated
public interface DefaultBehavior {
    ...
}

This comment was actually helpful because it not only tells me something was deprecated, but it tells me what replaced it.

Conclusion

While comments pose a risk, not all of them are bad. The important part is that you understand that risk and do your due diligence as a programmer to avoid that. Which comes down to:

Removing comments you don't actually need.
Rewriting code to remove comments if we can.
Make sure the remaining comments are helpful.
- This is done by clarifying why, providing examples, or being actionable.

Have questions? Let me know in the comments! I'm also easy to reach on Twitter.

The Repository Pattern: Properly Organizing Your Data Layer

Adam McNeilly — Mon, 20 May 2019 15:36:41 +0000

Originally published on Android Essence.

How to properly architect your application is a concern we as developers constantly face. There's unfortunately no one size fits all answer to it, and sometimes we don't even know where to begin. I've learned along my Android journey that the answer can also vary depending on what portion of your app you're trying to organize. Of course, you might say, it depends.

When it comes to your data layer, though, there are some really good tips on how to write clean, maintainable code. One of them is the Repository Pattern, and I'd like to provide a quick walk through of what it is and why it's important.

TL;DR

The repository pattern is a way to organize your code such that your ViewModel or Presenter class doesn't need to care about where your data comes from. It only cares about how to request data and what it gets back.

A Bad Example

Let's first look at what happens to our code when we don't implement the repository pattern. Let's say I have a detail page for a Pokemon (yes, I love using Pokemon examples), and I want to fetch the data from a retrofit service. I might end up with a ViewModel looking something like this:

class DetailActivityViewModel(
    private val pokemonAPI: PokemonAPI
) : BaseObservableViewModel() {
    ...

    init {
        job = CoroutineScope(dispatcherProvider.IO).launch {
            ...

            val pokemon = pokemonAPI.getPokemonDetailAsync(pokemonName).await()

            ...
        }
    }

    ...
}

While this may not look awful, it actually poses an interesting limitation. What if you were asked to fetch from a GraphQL API instead? Or even a local database? What if you wanted a mix, or to A/B test multiple approaches?

Depending on which one of those you chose, this gets really ugly. First and foremost, you'd have to add the relevant properties to your ViewModel, and then your ViewModel class eventually becomes bloated with data layer work that really doesn't belong there anymore.

If you've ever found yourself in this spot, even if you haven't yet hit this limitation (some people only use a Retrofit API and that's fine), you may want to consider helping your future self with the repository pattern.

Repository Interface

Going back up to the TL;DR, your ViewModel shouldn't care where the information comes from. In many programming problems where we don't care about the implementation of something, we can put the contract of what we do care about in an interface.

We can start there by defining our interface for what our data fetching behavior should be:

interface PokemonRepository {
    suspend fun getPokemon(): PokemonResponse
    suspend fun getPokemonDetail(pokemonName: String): Pokemon
}

Once we've defined that, we should update our ViewModel to use this interface:

class DetailActivityViewModel(
    private val repository: PokemonRepository
) : BaseObservableViewModel() {
    ...

    init {
        job = CoroutineScope(dispatcherProvider.IO).launch {
            ...

            val pokemon = repository.getPokemonDetail(pokemonName)

            ...
        }
    }

    ...
}

Now we're in a good place to take control of where our data comes from, and update it as needed without worrying about updating our ViewModel.

The Implementation

If you were someone who was only using one data source, like a Retrofit API, you only have to worry about creating one implementation, which can be done with some heavy copy and paste. In the Pokedex example, we converted our implementation to this:

open class PokemonRetrofitService(
    private val api: PokemonAPI
): PokemonRepository {
    override suspend fun getPokemon(): PokemonResponse {
        return api.getPokemonAsync().await()
    }

    override suspend fun getPokemonDetail(pokemonName: String): Pokemon {
        return api.getPokemonDetailAsync(pokemonName).await()
    }
}

Now, we can just update our call site for creating the ViewModel to use this implementation:

private val viewModelFactory = object : ViewModelProvider.Factory {
    override fun <T : ViewModel?> create(modelClass: Class<T>): T {
        val pokemonAPI = ...
        val repository = PokemonRetrofitService(pokemonAPI)

        return DetailActivityViewModel(repository) as T
    }
}

Multiple Implementation Example

This pattern is especially important if you want to consider multiple implementations for fetching data. A common example may be that you want to also fetch data from a local database, in addition to your network service.

Let's consider an example where we have an explicit offline mode that fetches data from a database. If your code is already using the repository pattern, we don't need to worry about updating the ViewModel.

All we would need to do is create our DatabasePokemonService and then we can conditionally pass that into the ViewModel:

private val viewModelFactory = object : ViewModelProvider.Factory {
    override fun <T : ViewModel?> create(modelClass: Class<T>): T {
        val repository = getPokemonRepository()

        return DetailActivityViewModel(repository) as T
    }
}

private fun getPokemonRepository(): PokemonRepository {
    if (offlineMode()) {
        return DatabasePokemonService()
    } else {
        return RetrofitPokemonService()
    }
}

Testing Benefits

When you move your data fetching code into an interface, you also make unit testing a lot easier! Our unit tests for the ViewModel don't have to worry about the data implementation either, we can just use Mockito to mock the interface and stub test data that way:

class DetailActivityViewModelTest {
    ...

    private val mockRepository = mock(PokemonRepository::class.java)

    @Test
    fun loadData() {
        val testPokemon = Pokemon(name = "Adam", types = listOf(TypeSlot(type = Type("grass"))))

        whenever(mockRepository.getPokemonDetail(anyString())).thenReturn(testPokemon)

        ...
    }

    ...
}

Now we don't have to worry about creating a room database in our unit tests, or a retrofit service. Dealing with an interface can help avoid all of those struggles.

Resources

I hope you found this helpful in understanding how to properly organize your data fetching code. If you want to see the repository pattern in action (although I don't do this A/B testing scenario), you should check out this Pokedex project on GitHub.

If you like analyzing the code directly, you can see the repository pattern implemented in this pull request.

Unit Testing RxJava or Coroutine Code With Constructor Injection

Adam McNeilly — Tue, 30 Apr 2019 19:56:06 +0000

Originally published on Android Essence.

Putting aside the long lasting debate right now about whether you should use RxJava or coroutines for your asynchronous code on Android, both camps often hit the same problem. How do I write unit tests for this?

Unit testing asynchronous code is tricky, because we may need to know how to properly test callback APIs, or perhaps we just want things to run instantly and not worry about thread changes. We may also be wondering how to handle not having a "main" thread in a junit test, unlike a connected test. This post will be focusing on handling that last one.

The problem

Let's start by first analyzing the problem. Let's say I have the following code to fetch Pokemon from an API:

open class PokemonRepository(
    private val api: PokemonAPI,
    private val disposables: CompositeDisposable
) {
    fun fetchPokemon() {
        val subscription = api.getPokemon()
            .subscribeOn(Schedulers.io())
            .observeOn(AndroidSchedulers.mainThread())
            .subscribe {
                // Do something with the response
            }

        disposables.add(subscription)
    }
}

Now, if we were to call this method from a junit test, we'll get an ExceptionInInitializerError because we're unable to mock the AndroidSchedulers.mainThread() scheduler. The solution to this would be to use Schedulers.trampoline(), which you can think of as an instant scheduler. There's a little more to it than that, which you can learn about in the docs, but it solves our use case.

The Solution

Unfortunately, with the repository code we have above, we can't easily change our unit tests to use .trampoline(). So we need to move the schedulers somewhere we can modify, like the constructor of the repository:

open class PokemonRepository(
    private val api: PokemonAPI,
    private val disposables: CompositeDisposable,
    private val processScheduler: Scheduler = Schedulers.io(),
    private val observerScheduler: Scheduler = AndroidSchedulers.mainThread()
) {
    fun fetchPokemon() {
        val subscription = api.getPokemon()
            .subscribeOn(processScheduler)
            .observeOn(observerScheduler)
            .subscribe {
                // Do something with the response
            }

        disposables.add(subscription)
    }
}

With the wonderful help of default parameters in Kotlin, we can supply the defaults to be used by the app which means at the call site we only have to supply two parameters just like before. Now, though, we can change the schedulers used inside a unit test:

class PokemonRepositoryTest {
    private val mockAPI = mock(PokemonAPI::class.java)
    private val repository = PokemonRepository(
        mockAPI,
        CompositeDisposable(),
        Schedulers.trampoline(),
        Schedulers.trampoline()
    )

    // ...
}

That's it! All we need to do to unit test our RxJava code is move our schedulers into the constructor. If you've already moved on from RxJava to coroutines, or are contemplating it, the solution to that is very similar.

The Coroutines Version

Let's consider we wrote some coroutines code like this:

class MainActivityViewModel(
    repository: PokemonRepository,
) : BaseObservableViewModel() {
    // ...

    private var job: Job? = null

    // ...

    init {
        job = CoroutineScope(Dispatchers.IO).launch {
            withContext(Dispatchers.Main) {
                startLoading()
            }

            val newState = try {
                val response = repository.getPokemon()
                // Handle success
            } catch (error: Throwable) {
                // Handle error
            }

            withContext(Dispatchers.Main) {
                // Post the new state to the UI
            }
        }
    }

    // ..

    override fun onCleared() {
        super.onCleared()
        job?.cancel()
    }
}

If we do this, we'll run into the same problem as our original RxJava code. Dispatchers.Main is only configured when running on Android, not inside JUnit. Also, we don't need the IO dispatcher, when we can just use Dispatchers.Unconfined for junit tests. Similar to RxJava, we could put them both as constructor parameters, but I decided to create a data class that would allow me to override any dispatcher:

data class DispatcherProvider(
    val IO: CoroutineDispatcher = Dispatchers.IO,
    val Main: CoroutineDispatcher = Dispatchers.Main,
    val Unconfined: CoroutineDispatcher = Dispatchers.Unconfined
)

class MainActivityViewModel(
    repository: PokemonRepository,
    dispatcherProvider: DispatcherProvider = DispatcherProvider()
) : BaseObservableViewModel() {
    // ...

    init {
        job = CoroutineScope(dispatcherProvider.IO).launch {
            withContext(dispatcherProvider.Main) {
                startLoading()
            }

            // ...

            withContext(dispatcherProvider.Main) {
                // Post the new state to the UI
            }
        }
    }

    // ...
}

Then, to call this in our junit tests, we can just override the dispatchers we want:

private val testProvider = DispatcherProvider(
    IO = Dispatchers.Unconfined, 
    Main = Dispatchers.Unconfined
)

That's it! Now we don't have to worry about the main looper being undefined for junit tests.

I've kept this simple to highlight how we can modify the Schedulers/Dispatchers that are used in our unit tests. For a full code example check out the resources below, or let me know in the comments or on Twitter if you have any questions.

Resources

I've just recently switched the project in this post to use coroutines. However, I did tag the last commit with RxJava code if you'd like to see how that was used and unit tested.

To see how to use coroutines in a project and unit test them, you can view this project.

Starting A Fragment For A Result

Adam McNeilly — Fri, 04 Jan 2019 14:38:33 +0000

A number of developers preach a single activity architecture on Android, which is something I've been trying to move forward to as well. In the process, though, I ran into one tricky problem. I don't have something like startActivityResult for fragments. If you're unfamiliar, startActivityForResult is a method that allows you to launch an activity with a specific request code, and when that activity finishes, your first activity will get a callback in onActivityResult and can do stuff with it.

This post is going to walk through how we can achieve that same affect using fragments.

Example

To walk through this concept, we're going to write a small application with two fragments. One is our DisplayNameFragment which displays a message like "Your name is: Adam", with a button that will navigate to a new fragment, SetNameFragment, where you can enter a name in an EditText, hit a finish button, and it will return back to the previous fragment and display whatever you put in the input. This is what it will look like:

Target Fragments

The key to this is using a target fragment. A target fragment is used when one fragment is being started from another, and when the first one wants to get a result back. I had used this concept in dialog fragments quite often, but didn't realize the same could be applied to other fragments as well.

Starting The Fragment

The first step is starting our SetNameFragment from within DisplayNameFragment. We can do that by putting the following code in the button's click listener:



  private fun launchSetNameFragment() {
      val newFragment = SetNameFragment()
      val tag = SetNameFragment::class.java.simpleName

      newFragment.setTargetFragment(this, SET_NAME_REQUEST_CODE)
      (activity as? MainActivity)?.replace(newFragment, tag)
  }

The MainActivity.replace() method above will replace the existing fragment inside a container with the new one that was passed to it. The fact that we use replace is important, and we'll talk about that in a second.

Returning The Result

Appropriately named, the fragment passed into setTargetFragment() can be retrieved in getTargetFragment() of the new one. So, inside our SetNameFragment, we can pass back the result by putting the following code inside the button listener:



  private fun returnWithName() {
      val name = name_input.text.toString()

      (targetFragment as? DisplayNameFragment)?.setName(name)
      activity?.supportFragmentManager?.popBackStackImmediate()
  }

In this example, we're expecting that the target fragment is an instance of DisplayNameFragment. My first instinct was to write a basic/generic way of handling this, but I've decided not to over engineer it.

When a name is entered, we pass that result back to the DisplayNameFragment by calling setName(), and then telling the activity to pop this fragment off the top, which will then reshow our DisplayNameFragment.

Handling The Result

Before I show you the code for the setName() method above, it's necessary to provide some background on fragment backstacks. How you use your backstack will determine how you can handle the results. Specifically, it can depend on whether you use an add or replace transaction:



  // Adds a fragment on top of whatever might already be in the container.
  supportFragmentManager.beginTransaction()
     .add(R.id.container, newFragment, tag)
     .addToBackstack(tag)
     .commit()

  // Replaces whatever is in the container with the new fragment.
  supportFragmentManager.beginTransaction()
     .replace(R.id.container, newFragment, tag)
     .addToBackstack(tag)
     .commit()

In the add case, a new fragment is just placed on top of the container. Nothing happens to the previous fragment. No lifecycle events such as onPause() or even onDestroyView() are called.

In the replace case, any existing fragments are removed from the container, and a new one is shown. This means the previous fragment runs through a couple lifecycle methods, including onPause() and onDestroyView(). It won't go all the way to onDestroy(), though, the fragment still exists.

I highly recommend this answer on Stack Overflow to see the lifecycle differences.

Using Add

If you're using an add transaction, the fragment is still visible on screen (just behind the previous one), so you're free to manipulate the view directly when handling the result:



  fun setName(name: String) {
      name_textview.text = getString(R.string.your_name_is).format(name)
  }

Using Replace

If you're using replace, though, the above code will crash. That is because the DisplayNameFragment view was destroyed so that it can be replaced by the new one. The above code would be trying to access a view that didn't exist, and so it would crash. To handle this, we can set the name in a class level variable, and read from it in onResume() to update our TextView:



  class DisplayNameFragment : Fragment() {

      private var name: String = ""

      override fun onResume() {
          super.onResume()

          name_textview.text = getString(R.string.your_name_is).format(name)
      }

      fun setName(name: String) {
          this.name = name
      }

      // ...
  }

This code wouldn't even work in the add case, because onResume() won't be called on a back press.

While it's a little more code to do it this way, I still prefer using replace transactions, but it's up to you and your needs. Just be aware that what you chose will affect how you pass information between fragments.

Conclusion

TL;DR You can use a target fragment to pass data between fragments in the same way you would use startActivityForResult() and onActivityResult(). You just need to be aware of how add and replace transactions affect the fragment lifecycles, and how to handle the result in each case.

If you'd like to see the full sample, you can find the project on GitHub.

Effective Database Design: Part 4

Adam McNeilly — Thu, 06 Dec 2018 22:43:05 +0000

This is the fourth and likely final post in a series about database design and normalization. In our last post, we learned about the second normal form. Up to this point, we have four things to keep in mind when designing our database:

Each table has a primary identifier.
Each column only has atomic values.
No tables have repeating groups.
There are no partial dependencies.

To recap, we currently have a database that looks like this:

Let's continue adding on to this database. As with the last posts, I'll explain the third normal form (3NF), show a design that breaks it, and show you how to correct it.

Third Normal Form

A table is in 3NF if it is in 2NF, and has no transitive dependencies.

A transitive dependency is when the following happens:

A determines B
B does not determine A
B determines C

If that didn't stick, let's show an example. Here we are going to revisit our classes table, and add the teacher's office:

id	class_name	teacher	office
1	Math	Smith	A107
2	Programming	Jackson	B205
3	History	James	A100

We can consider our key to be (id, class_name) because the combination of those will always be unique. The transitive dependency here is the following:

(id, class_name) determines the teacher.
The teacher does not determine the (id, class_name). This is because a teacher could teach multiple classes.
The teacher determines the office.

Therefore, we have a transitive dependency from the (id, class_name) to the office.

Problem

Why are transitive dependencies bad? Well, I mentioned teachers could teach multiple classes. Let's see what our table looks like when that happens:

id	class_name	teacher	office
1	Math	Smith	A107
2	Programming	Jackson	B205
3	History	James	A100
4	Science	Jackson	B205

If you've followed along with the other posts, you'll recognize the same problem again. We've got data redundancy, which can lead to a lack of integrity as a result of data anomalies. I could modify this table such that Ms. Jackson has two different offices, and I don't know which is accurate.

Solution

Once you find a dependency like this, you should isolate those related columns (teacher, office) and move them into a separate table. It's pretty likely that they represent a different entity, anyways - here, we're conflating teachers and classes together. Let's separate them.

We can have a teachers table:

id	teacher_name	office
1	Smith	A107
2	Jackson	B205
3	James	A100

And our updated classes table:

id	class_name	teacher_id
1	Math	1
2	Programming	2
3	History	3
4	Science	2

Now, after all of this effort, we have a database that meets 3NF:

Congrats! This was a lot to take in throughout all four posts, but you learned several essential criteria for a well designed database:

Each table has a primary identifier.
Each column only has atomic values.
No tables have repeating groups.
There are no partial dependencies.
There are no transitive dependencies.

There are even more normal forms, providing things to keep an eye on as your databases grow larger, but the five bullets above are an excellent starting point, and as much as I'm going to cover for now.

I hope you enjoyed this series, and please drop any questions for me in the comments and I will do my best to answer and update the posts as necessary. If you found these bite size examples of normalization easy to follow, let me know and I'll try to keep following up. :)

Effective Database Design: Part 3

Adam McNeilly — Wed, 05 Dec 2018 18:44:37 +0000

This is the third post in a series about database design and normalization. In our last post, we discussed the first normal form and took an initial step toward proper database design. We learned that we should have a primary key, atomic values, and no repeating groups. We also learned how to separate our entities to avoid redundancy.

Now we can go a step further and make sure we abide by the second normal form.

Second Normal Form

A table is in 2NF if it is in 1NF, and there are no partial dependencies. This means that non-prime columns (columns that are not part of the key, or possible keys) depend entirely on the primary key.

In a table that has a single primary key column, this will always hold true, so we don't need to stress about it. If we have a composite key, though, we could break this rule.

For example, let's add a teacher column to our student_classes table from the last part. Let's say that Ms. Smith teaches math, Ms. Jackson teaches programming, and Ms. James teaches history.

student_id	class_id	teacher
1	1	Smith
1	2	Jackson
2	3	James

The teacher column is determined only by the class_id, not by the entire primary identifier of (student_id, class_id).

Problem

Before we discuss a solution, let's look at the problems this could cause. Consider if Prince also took programming:

student_id	class_id	teacher
1	1	Smith
1	2	Jackson
2	3	James
2	2	Jackson

Notice any familiar problems? We have data redundancy issues. Twice we see that Ms. Jackson teaches programming, which also indicates we could be at risk of an update anomaly if I only changed one of those rows.

Solution

Since the teacher column is dependent only on the class_id column, we should group those entities together.

Let's put the teacher column in the classes table:

id	class_name	teacher
1	Math	Smith
2	Programming	Jackson
3	History	James

We've got a lot to keep track of in our three tables so far, so we'll just look at a high level diagram. Shout out to dbdiagram.io for making a helpful tool:

The 2NF was a quick one to explain, but now we've got a pretty well designed database. Let's recap everything up to the 2NF:

Each table has a primary identifier.
Each column only has atomic values.
No tables have repeating groups.
There are no partial dependencies.

We're in a good spot now that we know how to ensure these four things. In the next post, we'll continue on this normalization adventure to comply with the third normal form.

Effective Database Design: Part 2

Adam McNeilly — Tue, 04 Dec 2018 19:21:56 +0000

In the last post, we walked through the importance of proper database design, and learned about normalization - a process we can follow to ensure data integrity in our databases.

Normalization is achieved by making sure your database meets a number of normal forms. Each normal form builds upon the last, and each one makes your data a little better. In this post, we'll discuss how to achieve the first normal form (1NF).

First Normal Form

To ensure that a table meets 1NF, we need three things:

Each record is represented by a unique primary key.
Each column has only atomic (single) values.
There are no repeating groups.

I'd like to explain each bullet by starting with a table that is not well designed, and explain three steps we can take to achieve 1NF. Let's create a table that records a student, their year, and the classes they're taking.

name	year	classes
Adam	Freshman	Math, Programming
Prince	Freshman	History

Primary Key

Each record in a database table should have a unique identifier called a primary key. In many cases, this will be a number. In some cases, though, a string could suffice (think of a user name, or social security number - these should be unique among people).

A primary key is often one column, but does not have to be so. Two columns together could be the unique identifier for a record.

Our table so far has no unique identifier in any way. A student's name is not unique, nor is the combination of (name, year), nor is the combination of (name, year, classes). To resolve this, we can just add a unique id:

id	name	year	classes
1	Adam	Freshman	Math, Programming
2	Prince	Freshman	History

Atomic Values

When we talk about atomic values, what we mean is that it can not be divided any further. In plain English, this means we shouldn't have a list of values in a column. Thus, our classes column does not comply with 1NF, because we shouldn't have multiple values in one cell.

The quick solution to this, is to break them out into their own column.

id	name	year	class_one	class_two
1	Adam	Freshman	Math	Programming
2	Prince	Freshman	History	null

However, we've created a problem here.

Repeating Groups

A table should not have a repeating group of columns. What this means is, we should not have class_one, class_two, ..., class_n. The reason this is bad is because we would end up with a lot of null values for students who don't take N classes, and if there ended up being a student with more than N classes, we'd have to modify the table to add a new column.

The quick solution to this, is to treat class as one column and add a new row for each time a student takes a class:

name	year	class
Adam	Freshman	Math
Adam	Freshman	Programming
Prince	Freshman	History

Further Improvements

This design does comply with 1NF. This is, though, the exact same table we had in the first post, that I explained was not well designed due to data redundancy and integrity issues.

Another key concept of database design is ensuring each table only represents a specific entity. Here, we have the concepts of students and of classes together in one table. Let's break them out into separate tables:

A students table:

id	name	year
1	Adam	Freshman
2	Prince	Freshman

A classes table:

id	class_name
1	Math
2	Programming
3	History

The relationship between them can be captured separately, in a students_classes table:

student_id	class_id
1	1
1	2
2	3

In this table, the primary key is a composition of both (student_id, class_id) together.

I hope you found this helpful! The 1NF is an important step toward database normalization, and even making these few quick updates we have data that is far better than we started with. There's no redundant data, and we aren't at risk of any data anomalies.

In the next post we'll continue to add on to this database and make sure it complies with the 2NF.

Effective Database Design: Part 1

Adam McNeilly — Mon, 03 Dec 2018 20:40:18 +0000

Databases, while something I don't work with every day, have always been an interest of mine. I used to spend a lot of time on the StackOverflow MySQL tag just for fun. I've also spent a lot of time discussing database design with my roommate, and noticed a reoccurring theme among these conversations - we spent a lot of time discussing how to structure the database.

Questions that usually arise are "how should I organize this table" or "how do I handle a relationship between these two entities?" These questions are very important, because if we don't design our database properly, we can end up with something that will not be easily maintainable in the long run.

Let's begin with an example of an improperly designed table, and the risks we face as a result. Consider being asked to design a database table to record a student's name, year, and the classes they're taking. We may end up with one like this:

name	year	class
Adam	Freshman	Math
Adam	Freshman	Programming
Prince	Freshman	History

This table meets the requirements listed, but has a couple problems. This table has redundant data, and also lacks integrity. These two concepts are essential to proper database design.

Data Redundancy

Data is redundant if it appears more than once. I'm not referring to a specific word or identifier appearing multiple times. In the example above, there are two rows that say Adam is a freshman. This is redundant data that doesn't need to be captured twice, or even a third time if Adam took another class.

Data Integrity

Lifting an explanation from Wikipedia, "data integrity is the maintenance of, and the assurance of the accuracy and consistency of, data over its entire life-cycle."

In simple terms, I should be able to update, insert, and remove data without any negative effects on the other data. Consider our students table in the last section. It has the possibility for three data anomalies:

Update Anomaly - If I updated row 2 to modify the year column to be "Sophomore", I would have one record where Adam is a freshman and one where he is a sophomore. This inconsistency would not allow me to determine which row is correct.
Insertion Anomaly - If I wanted to insert just a new student, I couldn't do so. At least, not without setting the "class" column to null. Similarly, I can't add a record for a class without a corresponding student, and year. This limitation prevents us from properly recording data that may otherwise be important to us.
Deletion Anomaly - If I were to delete row 3, I have two problems. I've lost any record of Prince being a student, and I've lost any record of History being a class. This is a problem because I lose two pieces of information, even if I only want to delete one of them.

Normalization

So how do we design our databases to avoid these two problems? The answer is normalization. Database normalization is a process of organizing a database to avoid redundant data and ensure data integrity. A normalized database would not be at risk of these insert, update, and delete anomalies.

Normalization isn't defined by one single criterion. In other words, you don't just say "if we have X, then our database is normalized."

Instead, normalization is defined through a series of normal forms, each one building upon the last to ensure data integrity and avoid redundancy. There are several normal forms, and throughout this series we are going to work through three of them: first normal form (1NF), second normal form (2NF), third normal form (3NF).

In the next post we'll learn about this first normal form and how to design tables that comply with 1NF.