With years of experience in project work, our Android team has identified the most common pitfalls developers tend to fall into when implementing the user interface in Android apps.

Every Android developer will know the important role UI implementation plays in the development process. One could even argue that it is the most integral part of building a new app.

The UI allows users to interact with the features, functions, and contents of the application. When designed properly, it is user-centered, user-friendly, consistent, performant, accessible, and, most importantly, solves the problem that the app addresses. At any rate, you don’t want your app to look like it was built in 1990.

This article will point out the usual suspects that can mess up your UI implementation in Android apps – the most common mistakes developers make.

Before we start, we have to put one disclaimer in place. The article mostly focuses on building UI with XML, the old way. Jetpack Compose tends to bring forward its own set of mistakes, which is a story for another day.

The mistakes we discuss here represent the most common pitfalls Android developers will run into. We’ve learned to recognize them through years of experience working on various projects within Infinum’s Android team – from legacy ones to those boasting the latest technologies, modern architecture, and best practices.

Very often, we see developers fail to reuse their layouts. This can easily lead to:

A good principle that most programmers follow is DRY – don’t repeat yourself. In practice, we apply this by extracting duplicated code into functions or classes and reusing it like this.

But how to achieve the same thing in XML? One way of reusing an XML layout is to use the <include> tag. First, you need to create the layout that you want to reuse. For example, let’s create one called toolbar.xml. When you need to reuse it within another layout, you can do it in the following way:

Another way you can avoid duplicating layout code is by using compound views, an aspect of Android UI design that often goes overlooked. Many developers fail to take advantage of these powerful features, which can lead to issues in their app’s UI design.

However, there are situations where reusing layouts is not necessarily the best approach. Sometimes, maintenance-wise, duplicated layouts are a better choice. In such cases, it may be a better idea to granulate the UI into smaller reusable bits.

Let’s say you are trying to reuse one layout in a number of situations, but with each case you need to add more configuration parameters to it. This only makes your layout more complex to maintain and understand. In this case, it may be better to duplicate the layout and make the necessary changes instead of reusing and modifying it by passing a bunch of parameters to it. Maintenance also becomes easier later down the line.

Another common mistake we find is Android developers still using findViewById or Kotlin synthetics to refer to the elements declared in XML. It’s worth mentioning that Kotlin synthetics were removed in Kotlin 1.8. There are several problems this mistake can lead to:

Our suggestion is to use View Binding. This is a newer approach for accessing UI elements. It generates a binding class for each XML layout and provides references to all views in the layout. It also offers both null and type safety.

ConstraintLayout is one of the most powerful layout managers in Android. It was introduced back in 2017 and went on to become one of the most used layouts of all time. ConstraintLayout allows developers to create complex layouts with a flatter hierarchy. 

Failing to use ConstraintLayout can quickly lead to deep hierarchies, which make layouts hard to understand and cause performance issues.

However, there is also an issue on the other end of the spectrum – developers sometimes get so used to ConstraintLayout that they try to use it everywhere. Using it for a simple layout that can easily be done with a single LinearLayout or FrameLayout can lead to potential issues. For example:

MotionLayout is another powerful view group that is built upon the features of ConstraintLayout and adds support for animations and transitions between layouts. You should still use it with caution – while it is a great tool, it also adds to the complexity of the layout, and potentially increases build times and reduces performance.

One challenge that you are very likely to face during development is supporting the wide variety of screen sizes available on Android devices. 

Let’s take image sizes, for example. The lazy solution is to use one small image for all devices, which can make images blurry on high-res devices.

On the other hand, using one large image can cause crashes on older low-end devices that cannot fit the resources into their memory and spend processor time on downscaling them. This issue often goes overlooked since apps are mostly tested on a couple of newer devices. However, as soon as your app is released, it is installed on various devices, from low-end to high-end, using Android versions from 8 to 13.

The solution is to either use vector graphics or add multiple versions of each image adapted to different pixel densities.

If you need to support tablets as well, it might be a good idea to use different dimensions for different screen sizes. For example, by default, the content of the screen would stretch from left to right with a 16dp margin to the left and right. This won’t look good on a tablet, so a bigger margin would help. If you cannot adapt the tablet layout using dimensions only, it might also be a good idea to make two completely separate layouts – one for mobile and one for tablet.

Another tip for easily supporting more screen sizes is to make all your screens optionally scrollable. If the screen is big enough to display the whole content, it won’t be scrollable, but if the screen is smaller, then it can be scrolled to see all the content available.

Finally, it is important to know your target audience. Analytical data on your user base will tell you what devices they mostly own, so you can optimize your layouts accordingly.

The issue that probably every Android developer met at least once is related to handling theming and styles. Using hardcoded values instead of styles or referencing themes can lead to inconsistency between screens, and your app might end up looking unprofessional.

The biggest advantage of using themes is long-term maintenance. For example, if you wanted to change your primary color but didn’t use themes, you would have to change each component that contained it, one by one. When components reference the color from the theme, you only need to change one line of code.

Another great advantage of using a theme is that you can change the visual feel of your app completely with minimal effort. For example, when creating a dark theme, you can just copy your current one, change the colors, and that’s it. Also, with a proper theme setup, creating new screens usually takes less time.

Our additional recommendation is to use theme attributes. This is very useful when you want to define styles that can be applied to multiple themes; there’s no need to create a separate style for each theme. In other words, using attributes makes your styles theme-independent.

It doesn’t matter what technology is your specialty – if you work at a software company, chances are you are facing pull requests on a daily basis.

There are multiple benefits of getting your code reviewed. Reviews help improve the quality of the code, they are a good way to share knowledge between colleagues, and you are always in the loop about what’s going on with the project. As the saying goes, two heads are better than one.

However, when you have to review a pull request with more than 99 files containing over a thousand lines of code changes with absolutely no context, description, or links to tasks, that’s a problem. And to top it all off, such a request was opened at 16:59 on a Friday so it is the first thing you see when you come to work on Monday.

Fortunately, that situation can easily be avoided because anyone can improve their pull request description writing skills by following a couple of simple, but important steps.

According to Github, “Pull requests let you tell others about changes you’ve pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.”

In other words, the purpose of pull requests is to show your newly implemented code to your colleagues to get feedback. Contrary to popular belief, when creating a pull request, your main focus is not the code itself. You need to think about the reviewer, make it simple for them to process your code, and make sure they understand what you did and why you did it that way.

When a reviewer opens a PR that he is invited to, they get an unordered list of changes that had been done. This is not such a big problem with smaller PR’s but if there are multiple changes included in one PR, things tend to get messy quickly.

If that is the case, the reviewer can rely on another important thing – commits. Commits should be available in an ordered list, sorted by the time when they were created. Looking at changes commit-by-commit can be helpful, especially if they are accompanied by useful messages.

Still, there are some problems with this approach. The reviewer is missing the big picture of what had been done in a PR. A large number of commits can take a while to get through and most likely, the reviewer will be looking at code that’s already become obsolete. If you used so many commits, it usually means that you implemented something in, let’s say, commit number 13, and then completely overrode those changes in commit number 20.

To help our fellow colleagues, it’s a good idea to accompany pull requests with good descriptions. Technically, we’re allowed to write anything in a pull request message. However, describing in detail why our code does what it does can give the reviewer a much better understanding of the problem it solves. Any piece of relevant information that could be helpful to the reviewer should be included, such as links to documentation or design files.

When compiling a description, try to put yourself in the reviewer’s position and consider whether you would have a hard time understanding the code with the information provided.

If you find it too difficult to write a good description or you are already two pages in and still have plenty to say, it might be a good idea to break your PR into multiple small ones.

The reasoning behind this approach is simple. It’s much easier to review smaller pull requests than go through hundreds of file changes in a single one. The larger the pull request, the higher is the chance of missing a bug or an edge case. Additionally, smaller pull requests get reviewed faster and are easier to merge since there tend to be less conflicts.

When you’re adding a large portion of new code, it is much better to make multiple, logically organized pull requests. Your VCS provider can be of help here because it probably enables you to stack your PRs on top of each other and then handles their re-targeting when the base gets merged.

Keep the person who is going to be reviewing the PR in mind. You are making their life easier when your description is formed in a way that brings them up to speed with minimum information.

If the reviewer is familiar with the codebase, it will generally be much easier for them to check your code changes and their interactions with other code.

You need to define what problem you are trying to solve, usually in the form of a ticket.

You’ve probably set up your VCS provider (e.g. Github) to link your tickets to their respective PR’s automatically. If not, I highly recommend you set it up that way using official Github information. In case you don’t use that setup and have absolutely no desire to start, a link to the task/ticket should also be enough.

Generally speaking, complex problems require more detailed explanations. However, you should bear in mind that complexity is not necessarily correlated with the number of line changes that you performed. For example, one of the longest pull request descriptions I wrote was for a one-liner that caused a subtle memory leak. Without a detailed description, the reviewer would have a hard time seeing why that particular change fixed the issue.

When something requires a detailed description, it’s also a good indication that the code itself would probably benefit from some comments. If your solution was hard to explain to the reviewer, other developers working on the project might have a hard time understanding it, too.

When you’ve described the problem, you’ll need to explain your solution, too. Help your reviewer by providing answers to three questions about your implementation – what, how and why.

First, tell them what you changed. Use two tabs in your browser, one for writing the description and the other to check the files. Go through the changes one by one and write down one sentence for each of them. This way, you explain your actions to the reviewer and address any unusual or confusing parts of your PR upfront.

Since you’re the one who has opened the PR, you probably know best what changes will be most confusing for the reviewer.

The next thing that you’ll want to write down is how you did it. For example, you can state that you took the implementation from another project, removed unnecessary code, replaced a library, etc.

Finally, you help the reviewer by telling them why you did it that way. Perhaps you wanted to try out a new approach, needed to improve performance, or something similar.

Optionally, you can create a checklist or a template for yourself (or your team) of what you need to do before opening a PR. For example, include the ticket, include all changes, provide screenshots/videos, etc.

If you find it too difficult to explain something in the description, feel free to start writing comments that point directly to individual lines of code. You can then group related changes together.

If the UI was changed, provide screenshots. Even better, provide the “before” and “after” screenshots. Videos are usually really useful when you need to show an app’s flow. Again, try to use “before” and “after” shots.

We’ve covered writing pull request descriptions like a pro, but what happens if you’re on the receiving end? The reviewing process can be just as complicated as opening a high-quality pull request, if not more.

Luckily, there are some tips and tricks that can speed up and improve your reviewing skills.

When I’m invited to write a review on a PR, I find the approach from this article helpful. Here’s an example:

Don’t write: This is not worded correctly.

Do write: Suggestion (non-blocking): This is not worded correctly. Can we change this to match the wording on the marketing page?

This way the author of the PR knows that this is in fact only a non-blocking suggestion, while the reviewer is already providing a possible solution. Another example:

Don’t write: Issue (blocking): According to the design, these buttons should be red. Please change it.

Do write: Suggestion (security, blocking): Let’s try not to use SHA-1 since it is not recommended anymore. Try to use its cryptographically stronger counterpart (SHA-2 or SHA-3).

With this approach, you and your team you can define multiple labels to use and improve your code-reviewing experience.

Try to avoid saying change this, do that, improve this, etc. and use phrases like Have you tried this in order to achieve better results?, Let me know what you think, Have you thought about this? It may better solve your problem in my opinion.

Try to avoid the words should and must.

Finally, if the PR is too big and you find it too difficult to review, feel free to request a more detailed explanation, more screenshots, or in the worst-case scenario, request the PR to be broken down into smaller pieces.

If a reviewer left some comments that require a response, it is your responsibility to answer them, and do it as soon as possible. This shows respect for your reviewer’s time because they will be able to continue reviewing the code without lengthy pauses.

Merging your code into an existing codebase is a two-step process. First, you need to write your code so that it is clean and correct. The second part is presenting what you did to the reviewer in a simple and understandable way, which saves both your and your reviewer’s time.

Each pull request requires a specific approach. The person opening the PR has the most information to put together a quality pull request description. They know the context, what was done and why, who is the reviewer, and any additional information that might prove useful.

Instead of blindly following the instructions above, just use common sense. You probably don’t need three pages of explanations and five screenshots if you’re just removing a harmless comment or slightly reformatting the code. Don’t try to force yourself to use each and every step described here, but instead only use the parts you believe will reduce the burden on the reviewer.

Hopefully, these tips and tricks will help you write better pull requests, which makes the whole code reviewing process quicker, easier and ultimately leads to better results.

This article was co-authored by Anteo Ivankov.