Developing for developers: Working on an Android library
If you want to develop an Android library or you are already working on one, these suggestions will help you to apply some good practices to achieve high quality software.
This is an unified translation of the original articles published in Spanish language: Part 1 and Part 2
When talking about Android development we use to think that the product that we are creating with our code will end up as a published application. We also use to think that people that receipt our work are always the final users: they will install and use our app on their devices (smartphones, tablets, smart TVs, cars, etc).
That’s a possibility, but it’s not the only one.
In the middle of our development process, we can identify that we are finding a solution that can be useful to someone else because it solves a common problem, simplifies some kind of task, encapsulates a reusable feature, etc. So, we are in front of new opportunities: the code we are writing is not just ready to be installed on a device. It can be really useful for a lot of developers. It’s time to create a library!
Here are some suggestions that may be helpful to you.
Think like a developer
Of course you do. But now that you are developing a library, think like the developer that will use it. Consider the following:
- Ease for installation and initialization (or no-initialization at all): The less mandatory steps to configure your library in order to start to use it, the best. Although it’s important to offer a certain level of customization, don’t forget to provide default settings.
- Code consistency: Follow principles to not confuse your user. Similar operations have to be done on similar ways. For example, Builder design pattern is often a good option to instantiate objects. This way, code is clear and offers flexibility to create complex objects specifying just the needed parameters or any other combination.
- Remove limitations: The usage of your library inside a project should make your user’s life easier, not to complicate it. For example, don’t abuse of some limiting features of OOP: Prioritize composition over inheritance, as the last one is more restrictive on some languages.
In the other hand, your implementation should not be an obstacle when writing unit tests. For example, avoid the exposure of classes with static references from your API, as they difficult the way to provide theirselves as mocks. - Implement logging: Your library should give visibility on the operations that are being executed. Use the proper log levels. It’s important to developers to follow the processes that are running and also see what’s failing. An improvement could be to offer a debug mode. So, when initializing the library, the developer is able to specify if logs must be displayed or not. About the implementation, you can use a log wrapper that basically will decide if logs will be printed in console or not. You can implement from scratch or use an existing library like Timber.
Use Exceptions with clear messages if a precondition isn’t met. - Avoid collisions: Ensure that your library’s code does not interfere with the application that’s using it. For example, the resources (layouts, strings, drawables, etc) could be named with a prefix to be clearly recognizable if they need to be overriden, and also it will avoid any naming conflict.
Deliver updates effectively
Android libraries results on .aar files that can be installed downloading the file and manually including it inside a project. That’s not the suggested approach as you will depend on that manual action every time you want to provide an update. So, I suggest to you to use an artifact repository so your library will be available to be downloaded as a Gradle dependency. Some popular platforms are Github Package, JitPack, Nexus and JFrog.
When distributing your library that way, users can take advantage of the Android Studio’s automatic updates check that will notify them on new available versions. Also, you can provide transitive dependencies that will be automatically downloaded, keeping your library light.
Consider backwards compatibility
You may need to change a function signature, a class name, or delete code after a refactor. Consider that you will be affecting the compatibility with those applications that already adopted your library. For example, if you realize that you can remove some code, it would be a good practice to first mark it as Deprecated. You may keep it during a couple of versions to give your users some time to make the necessary changes to adopt the new API and ensure it won’t be a blocker to adopt new versions.
It is also a good practice that the naming policy you use to define versions is consistent with the changes introduced. The most common one consists of three parts: Major, minor y build. For example: 1.0.2. If you are consistent with your version names, your users can get a first impression of the types of changes that differentiate one version from another.
Provide documentation
It’s important to include set up instructions, a basic usage example and customization details to take the maximum of advantage. If it contains UI components, to include screenshots and GIFs adds a lot of value.
- Keep your README.md file updated. It’s the entry point of your library and it may be decisive for its adoption. Include compatibility requirements as Java version and minSdkVersion of Android API. Use markdowns correctly: apply proper format to code blocks. Add badges. It is sign of transparency and inspires confidency to see the build status on CI server, code coverage in terms of unit tests, latest version on artifact repository, etc.
- Don’t forget to maintain a changelog containing every new feature, bugfix and breaking change. The set of all this information is commonly known as release notes.
- Add Javadoc to your classes for easy reference during the development process.
To show the capabilities and the way of use of your library, I suggest to include a sample project that can be helpful to others developers as a starting point to make quick proof of concepts and ensure that it covers the business needs.
Modularization
A well-known Android limitation is the number of functions that can be contained on a single DEX (~64k). Of course, multidex could be a solution. But at this point, we must wonder if it’s necessary to our library to contain such a large number of functions and if it could affect in a negative way the projects that uses it.
Given that, we may evaluate the possibility of separate our Android library in several modules, independant, reusable, that can be included as dependencies depending on the needs.
A clear example of this approach is the action that was taken with the Play Services library. It’s currently divided in different dependencies (Maps, Cast, Fit, etc)
Pay attention to the security
Although the interface of your library must be clear for its use, you must know how to separate what you want to encapsulate. Do a proper use of function access modifiers to prevent misuse.
You can even use Proguard to obfuscate the code that should not be visible to the programmers who will use your library. It’s usual to not use it directly. You can just document the rules that must be included on the final project instead.
One more thing: when possible, you may offer a channel where users can collaborate with you, giving feedback. They will help you with ideas and bugs reporting. As it happens on all the development processes, keep in mind that it will be changing. Provide support and keep it updated.
So, you are now ready to develop your library. The developer’s community will be really thankful!
