Building maintainable Android applications

Why should you care about maintainability when everything already works? It’s not a bad thing to try out new things with prototypes to increase your knowledge, but when you start building applications that will be used for many years and that will grow larger and more complex, you want to make sure you can keep adding to it without running into problems. When many people need your software to do their work every day, you cannot afford to build something that will collapse under it’s own weight. So, here are a few guidelines to help you:

Keep your code clean and documented
When you have to go back regularly to modify your old code, having clear names and documentation is very valuable. You only write a piece of code one, but it will be read again many times so you should make that job as easy as possible. Having a consistent coding standard also helps a lot with readability: it is jarring to read code that jumps from one coding style to another, and you want to concentrate on the code and not how it looks.

Also, I don’t believe that all code can be self-documenting code. It’s a good thing to aim for, but sometimes you have to do hacks that are not as clean: a little explanation can go a long way when you try understanding it again a few years down the road. In other cases, for example when you implement a complex bit of business logic, you will need to know what the code was supposed to do if it does not behave as expected or if the logic needs to be changed later on.

Don’t do complicated when you can do simple
In keeping with good Agile principles, you don’t want to plan everything that’s even going to happen in you application before getting started. Don’t get me wrong, you should have an idea of where you’re going and have a basic architecture planned out, but keep thing as simple as possible while still being organized. You can always refactor a complex bit of code to add one more layer of abstraction as needed and optimize the bits that are not as effective, but having a relatively simple architecture planned out helps keep everything clean and makes it easy to introduce new team members to a project.

You should also avoid clutter in your code base. First, fix as many compilation warnings as you can: some may not be important to you, but you don’t want to risk missing a new warning that shows a real problem. It’s something small and silly, but it makes it harder every time you need to modify something. Also, only implement the methods you need and don’t keep old code lying around to limit the amount of code you have to maintain. If you need to reuse the code you deleted later on, you can always retrieve it from your source control system.

Limit the number of external libraries
There are many good libraries available in the Android and Java worlds. But while using a library can save you time, it also has has a real cost: when you upgrade your application to support the newest Android version, you also need to upgrade all the libraries you use. Each dependency is a part of your project that can break and on which you have no direct control. Libraries can also stop being upgraded, which will eventually require a re-factoring to an alternative or an effort from your part to maintain the old library, which can be be costly.

On the other hand, using a library it can be worth it if you need to make a quick prototype or to add a component that would take too long to built. But for mission-critical stuff that can make or break your application, you may be better off making your own implementation based on your needs. Fortunately, nothing is stopping you from learning from the existing libraries to make your own thing. You may also prefer to use methods from the standard Android SDK version even if their implementation is not the best: it is the most likely to have been tested on a large range of devices and to be maintained for a long time.

Your product is not your debug version
If your code works when loaded from your development machine to your testing device that’s great but it’s not the end of your job. You need to test your release version on at least a few more device and Android version to be sure it will work when released to the store, since not everyone that will use your application has the same device and OS version than you. You also need to keep testing when new versions of the Android OS keep coming out so it does not break for your users that like to keep their device updated with the latest and greatest.

Also, if your application is not deployed via the Google Play store, you may also wish to add some form of debugging to your application, for example a logging mode that can be toggled on to report a problem to you: it can be pretty hard to help a user when the only information you have is that your application crashed. Finally, you also need to have some documentation ready for your users, unless your application is very simple. A little FAQ on your website may be enough to do the job, but don’t leave your user totally in the dark trying to understand your application. This will reduce the number of support requests and give you a few answers ready to go when the questions start coming in.