Using Open Source

Web development is powered by open source. From the operating system all the way up to the JavaScript libraries or CSS frameworks, reuse of open-sourced results of hard work of thousands of developers helps us build our products faster and more reliable.

But today there are dozens or hundreds tools, libraries and modules available for any given job, and often it is hard to pick the best one.

When choosing the component that your’re going to rely for the rest of your product, you have to keep in mind you’ll depend on it for stability, improvements, and will surely spend at least some time improving the component yourselves. So it’s important to pick one that will result in net benefit, instead of extra cost in time spent debugging, workarounds, and sunk into improving it.

Here are some rules of thumb I find useful when discerning between available options:

1. Fitness for a particular purpose

The first filter is whether a component actually does the entire job. Often this will be the case, but sometimes additional work will be required to modify and extend the component to do what’s needed in our specific use case. If extra work is done, it is also beneficial to push it upstream so that you contribute back, but also to ensure that your specific changes don’t bit-rot when the original component changes with time.

2. Project health

Is the component actively developed? Once you start using it, you’ll likely encounter edge cases, bugs, or need to do some modifications. Although you’ll probably want to invest own time in the project, you want to ensure you’re not the only one, and avoid becoming a new maintainer.

Number of commits, or number of merged pull requests in the past few months is a good indicator of project help. So is the activity around bugs - how many got closed or at least commented upon in the past few months. Mere count of bugs is not an indicator - a lot of open bugs (issues) may just mean that the project is big and used by a lot of people.

3. Code quality

In the same way you care about the quality of your own code, you should care about the quality of the code you rely on. Besides the fact that you expect it to work correctly, you also want to be able to dive in and check assumptions that may not be documented, fix bugs, or implement new features.

Do a thorough code review. If the code is below the standard in your own team, if it’s unreadable or you can’t figure out how the whole thing is put together, avoid the project. If you skip on code review when picking a third-party component, you may be in for a nasty surprise later on when it’s much harder to evict it from your project and change components. 4. Stability

There is such a thing as too quick pace of improvements and changes to the software. While it’s great that improvements are made, you also want to be sure that breaking changes, or the changes that require you to modify your own code, are few and far between - in other words, that the software is stable.

To check for stability, look at the project’s change logs and new release announcements to check whether they’re mentioning backwards-incompatible changes and how often. Also check whether the project is following semantic versioning or similar scheme to indicate which versions are compatibility-breaking or not. 5. Documentation

The better and more complete the documentation is, the easier it’ll be for you to use or extend the component. This is a no-brainer, but take care not to be misled by nowadays-popular flashy project pages and trivial-seeming quickstart docs - dig deeper.

In the end, remember that the code itself is the ultimate documentation. Some projects, such as Underscore.js have annotated source code with is a delight to read and servers as a great low-level doc, in addition to detailed API reference. 6. Community

When talking about open source, community is strength in numbers. If a lot of people are using the component, it’s more likely the bugs are found and ironed out faster, it’s easier to find help (for larger projects, on their dedicated forums, IRC channels, or in sites such as StackOverflow) and it’s more likely there is documentation (even 3rd-party) on the project.

For small projects though, it’s likely the community is very small (basically nonexistent), so the lack of community, if a project is very niche, may not be a bad sign. When comparing multiple projects targeting the same niche, a comparison of their relative sizes is a good indicator though.

For projects on GitHub, Bitbucket and similar online repositories, an easy way to get an indication of the community size is to look at the number of people who “starred” or are “watching” the repository. Bad or nothing

But what if you, after all your search, can’t find a single acceptable project that you can rely on, instead only finding low-quality, unmaintained, undocumented half-finished projects?

Then it’s time to look at the least-worst and ask, whether it’s faster to implement what you need in house, or take over the project, fix it and modify to do what you need. Sometimes doing it in house will be faster, but many times it would still be faster to resurrect and renovate a dead project than starting from scratch. There’s no single right answer here, but it’s a question worth exploring. Contribute back

Whichever project you do choose to rely on, consider contributing back. Besides altruism, it also makes economic sense. By contributing back your improvements (bug fixes, feature additions, or “mere” documentation or bug reporting), you’re ensuring that the future maintenance cost of your changes is spread onto entire community, instead of being borne by you alone.