Developing Android libraries that are easy to use – Part 2: Common mistakes to avoid

This is Part 2 of the series Developing Android libraries that are easy to use. You might want to start by reading Part 1.

This post is basically the inverse of the previous post. Here we discuss what not to do / what to avoid.

1. Documentation location

The following are the don’ts for documentation location:

• Don’t add documentation to a location that is not directly linked from the code repository page (e.g. via Bitbucket, Github, Gitlab or wherever your code is stored) or library website.
• Don’t spread documentation over multiple locations without a table of contents – the readme.md should have minimal content, if you have a Wiki, add a navigation section on the left or right.

2. Library setup

The following are the don’ts for the library setup:

Don’t use personal repositories or non-conventional repositories.

This adds an extra step that most developers have difficulty understanding since projects can have multiple repository blocks in different build.gradle files on a single project. It also becomes confusing to understand the difference between the repository block for buildscript and allprojects. In some cases, a project can have multiple allprojects blocks. Try as much as possible not to do this, and if you do, clearly document it in your setup documentation.

Do require only a single import of your library.

Don’t require excluding files/dependencies after importing the library.

Don’t require importing extra dependencies explicitly, i.e. don’t require the developer to add other dependencies in their dependency block.

When extra configurations are required, the developer needs to understand where the configurations are set, what they mean, the minimum they need to configure to get it working, and how to achieve what they want. Try as much as possible to provide defaults and make it modifiable.

3. Sample code

We recommend having sample code to serve as a test lab, reference code, and proof of concept. The best way to get others to start using your library is to make it easy for them to do so.

The following are don’ts when writing the sample code:

• Don’t write undocumented sample code.

• Make sure to have a sample app — Basically the app module needs to be working and running. It’s even better if it imports the library from the AAR and not the project module source code.
• Don’t require configuring keys & tokens without stating this in the readme.md.
• Don’t fail silently when mandatory keys or tokens are not configured — Fail fast and loud when mandatory configurations are missing.
• Don’t require customizations on the sample/demo app — Provide default working keys and configurations where possible. The app should run easily without any further work.

That concludes Part 2 of Developing Android Libraries. In the third and final part we’ll discuss the technical details of Android libraries.