UML for Android Engineers

Working on a real-world Android app isn’t just a matter of writing code. Most of the time you work in a team, and the code must be tested, but also well documented. Many people say that the code should be self-explanatory and you should understand how the app works just by looking at it. This isn’t completely true. Sometimes you need a way to represent the architecture of your app, check dependencies between different components or see how classes are related to each other. At the same time, you need to communicate with your colleagues in an easy but very expressive way using a quick diagram on a scratch paper or on a whiteboard. But how can you do that?

In this tutorial, you’ll learn everything you need to know to document your Android app using Unified Modeling Language (UML).

You’ll learn:

• What UML is and how it helps you document your app.
• What you can say about your app using a deployment diagram.
• How to represent the dependencies between different components. This can help with understanding the Dagger dependency graph.
• What a class diagram is and what the main relations you can describe are.
• How to represent how different components collaborate to achieve a specific task.
• What the state of your app — or part of it — is, and how can you move from one state to another.

UML is a very big topic, but in this tutorial, you’ll see just what you need for a typical Android app.

Getting Started

In this atypical tutorial, you won’t write a single line of code, but you’ll use the existing Poster Finder app.

Download the project by using the Download Materials button at the top or bottom of this tutorial. The app uses data from the Open Movie Database API website, which requires a free key and allows a maximum of 10,000 requests per day. Once you get the key, you need to add it to your local.properties file like this:

// ...
omdb_api_key="INSERT_YOUR_KEY_HERE"

Build and run the app, insert the text Indiana into the EditText at the top and press Enter. You’ll get something like the following:

Poster Finder app

As you’ve probably guessed, you can use this app to search for a movie and display its poster by clicking on the image. You can play with the app and see how it works from a user’s perspective. But how does it work internally? How is the code structured? That’s what you’ll map out using UML.

Understanding UML

You probably already know that UML is a standardized modeling language consisting of a set of diagrams. It was developed to help system and software developers specify, visualize, construct and document the components of software systems.

That’s an intimidating definition, and it might make you think that to use UML you’ll need some very complicated programs with expensive licenses. That’s not true — or, at least, it’s not true anymore.

Each UML diagram must be:

• Focused: Every UML diagram should describe just one single aspect of a system and answer a very specific question, like: What are the main packages of the app? How are they related to each other?
• Simple: You should be able to draw a UML diagram on the fly on a small piece of paper or quickly on a whiteboard. You don’t need an expensive tool for this.
• Intuitive: Each UML diagram should be very easy to understand. As you’ll see, UML is a typical example of the Pareto principle: With 20% of the UML standard, you cover 80% of cases. For the exceptions, you just add some notes with additional information.
• Quick: You should be able to draw a UML diagram very quickly because it should only express one thing.
• Open: You don’t need to follow some strict UML convention. UML is a language that you can twist at your will as long as it helps describe a system. An example of this is the concept of stereotype you’ll see later.

Although you can draw a UML diagram on a small piece of paper, in this tutorial you’ll use LucidChart.com. This is an online tool for creating some basic UML diagrams with a free account. This is just one of the tools you can find online. However, you could use any other tool or, of course, a piece of paper.

Deciding What to Document

As stated earlier, each UML diagram should have a specific goal or answer a single question. You shouldn’t create a diagram to explain something that’s obvious.

In this tutorial, you’ll use UML diagrams to answer the following questions:

• What does the Poster Finder app do?
• Who’s the Poster Finder app interacting with? And how?
• What’s the structure of the Poster Finder source code?
• What are the main classes and other abstractions? How are they related?
• What’s a stereotype and how can it help you document your system?
• How do you describe the way different objects collaborate to achieve a given task?
• What about asynchronorus communications between objects?
• State is an important concept. How do you represent different states and the transitions between them?

UML provides the tools to answer all those questions.

Creating Use Case Diagrams

The Poster Finder app allows you to search for a movie by name and then displays its poster, if available. How can you represent the main use cases of the app with a diagram? In UML you do this using a use case diagram. That’s a way to answer the following questions:

1. Who can access the app?
2. What can a user do with the app?
3. What are the main features of the app?

Consider the following use case diagram.

Use Case Diagram

What does it tell you? It tells you that:

1. You’re in the context of the Poster Finder app. You represent this using a box as a boundary for the app and putting the name at the top of it.
2. The Poster Finder app doesn’t need any particular credentials and any user can access it. You use a stylized human symbol to represent any actor (user).
3. You represent any use case with an oval containing a short description. In this diagram, any user can simply display the poster for a movie. To do this, you need to access other functionalities.
4. To display the poster for a movie, you need to search for the movie title. This is another use case that you need so you include it in your use case. You represent the inclusion using the dotted line with an open arrow with the «includes» description. As you’ll see later, any description between «» is called a stereotype. You do the same for the Display Movie Details use case.

This is the use case diagram for the Poster Finder app, but it’s also worth giving a quick example of a more complicated case.