Dependencies are an essential part of each software project. Without utilizing existing libraries the scope of a project explodes because you can’t solve every problem by yourself. Today we rely heavily on open source libraries to get the work done for us. Basically there is a library for nearly every problem and every language. But how do you pick a library especially if there are multiple of them solving the same problem? What are the requirements for a library to be used in commercial software? How do you measure the quality of a library? These questions come to my mind every time I need to decide on a dependency. Over the years I have created a criteria catalog in my head that I want to share with you in this post. So, if you are the author of a library please don’t feel offended, I’m just describing how I pick dependencies.
Be open
In more than 10 years of software development I have never done a project were we have bought a commercial library. Open source libraries are essential for us. If there is no open source library solving our problem we simply create one and open source it instead of buying a commercial solution. So, if I’m searching for a library and stumbling upon your library on github or sourceforge (or something similar) within the first search result you have done an amazing job! You are actually describing the problem your library solves and that is what I’m searching for. I don’t search for fancy names like “humble bumble super library”. I will search for “How to solve problem X”. So, let’s see if your library survives my pickiness.
Provide a License
I’m a professional software developer. This says nothing about my skill but it tells you that I’m developing software for money. I’ve been creating commercial software for years which means we are selling our solutions to customers. If you provide a library that solves my problem the first thing I look up is if your license fits my needs. You don’t have a license for your library? You are out! Providing the licensing model for your library is a real must have for me. This is because when creating commercial software the right license is important. Licenses like Apache License or the Eclipse Public License work just fine while GPL is questionable. So, please think about licensing and provide the licensing model used at a place where I can easily find it.
Be Active
I found your project, good Job! Now tell me what you have worked on recently. A nice thing about e.g. github projects is that I can see on the first look when you have done your last commit. Was it a week ago? Perfect! Was it 6 months ago? I’m getting suspicious! Why haven’t you done anything on your project in 6 months? Of course there could be several reasons. If your project has matured enough and there is nothing left to do (yes, this happens sometimes e.g. for parsers) please tell me. Just point it out in your README like “Parser done. No bugs left. Stopped working on it. Report issues if you can find one and I will fix them”. That’s enough, now I know that you must have done an awesome job. If I can’t find something like this I suspect you have lost interest in this project and the same is true for me as well.
Tests… must have!
One of the first and most important things I look up when picking a library is if there are automated tests. If not, you are out! Testing is a real essential to me. I have created so much code over the last years to know how important it is to have automated tests. I’m really strict about it. If a project does not have a set of automated tests I simply can’t trust it, it’s that simple. I don’t care if you are using unit tests, integration tests or UI tests. Just tell me that you have tests and that you run them on a regular basis. The best case is that you run them with every commit and you are transparent about the results. Build services like Travis CI or codeship make it really simple to create build jobs and provide feedback directly in your project.
Tell me your coverage
You have a set of tests? Great! Now tell me how good your tests are. Over the last few years I’ve noticed projects publishing their coverage reports. Services like coveralls make it really easy to be transparent about coverage reports. If you have a coverage over 80% I’m starting to like your library before I have seen any code. It tells me you care about tests, too.
Be consumable
After finding your library I will probably take a look at it by adding it to my project to play around. So, please tell my how I can consume it! I really don’t want to end up sitting on my desk and spending time to figure out how to compile your library myself. These times are over! Every language has it’s own standards of how to manage dependencies. Utilize them! If you do a Java project, just publish to Maven central. If you are doing an iOS project, create a cocoa pod!
Tell me how to contribute
It’s important to me to know how to make changes to your library myself. But I really don’t want to spend much time to figure out a complex setup. Just tell me what I need to do to get my hands dirty! Tell me also what you expect of my change. You have a policy like “No Tests, No Merge”, great! I love it. But you need to tell me. Project hosting platforms like github have build in features for this like the CONTRIBUTING.md feature. Use it!
Be responsive
Responsiveness is one of the key things to me. I don’t mind if it takes some time until a bug is fixed but please respond to me with a comment. Let me know that you care about your users. After creating an issue and don’t getting an answer for 2 weeks I consider you were hit by a bus and your project is dead. Also if I spent some time and put work into your library please respond to me as well. I don’t mind if my change does not fit the “standards” of your project. But please tell what I have done wrong and I will come up with an improved version shortly.
Don’t make me search your documentation
With all the work you put into your project to show me your tests, coverage, contribution guidelines and so on you have gained my interest. Now, please don’t make me search your documentation. Add a link in the first section of your README files pointing to your documentation. It’s one of the first things I will look for. I rarely use a library that does not provide documentation. Of course there are exceptions. If your library is the state of the art String util, the scope of the project is so small that I don’t need documentation. If it’s getting more complicated I do need documentation for sure!
Provide good documentation
In my opinion “good documentation” is not well defined when it comes to software projects. For me there is only “I get it” or “I have no idea what this is about”. One example of a documentation I consider as good is the Guava documentation. It’s more of a user guide which is categorized really well. I can find the topics of interest real quick. The authors also made a good job telling my why they provide features by providing examples of problems they can solve. An example of bad documentation are projects that just publish documentation in the form of JavaDoc or similar. I don’t need this published. My IDE will present it to me! But the level of such documentation is not high enough. You need to tell me what features do exist and which problems they are solving before showing me classes and constructs. Later you can tell me the locations in the code where to look up the details. And yes, I will look them up!
You have done all this? Congratulations, you gained my interest and trust. I will use your library, I will care about it, I will contribute to it, and I will recommend it. You have won yourself a passionate follower.
The reason why the topics above are important to me is because they tell me things about your software but more importantly they tells me things about you as a developer or developer team. If you care about providing such information to me I can imagine how you are working. This creates a bond between us because I care about the same stuff!
As always, please feel free to disagree on my list. It’s just a collection of things I have observed over the last years and think are useful to others as well.
