Hand pick the right software project for your situation

What I look for in projects

With so many software projects available for any given purpose in the Java ecosystem[1], it’s critical to think about how one can evaluate the suitability of a given library or tool.

comment on this article

There’s no way to actually come up with an objective grading system that works for everyone; what stands out to me likely won’t have much of an impact on you, unless someone were to somehow put together a Netflix-like recommendations system for libraries and tools – and even then, what I need isn’t going to be the same as what you need, so my recommendations aren’t likely to be worth the paper they’re printed on in any event[2].

However, I can offer some thoughts on some things to consider when looking at projects. The importance of each aspect is an individual choice, of course, and it’s very likely that you’ll be able to add criteria. This is what’s supposed to happen, and I can’t presume to have covered every possibility.

There are eight major topics that I consider when looking at a project. They fall into two major groupings, which I’ll call “conception” and “execution.”

“Execution” issues are technical and legal concerns, effectively non-negotiable elements that aren’t affected by the person doing the evaluation.

“Conception” issues are those things that cover subjective things like documentation. Someone intimately familiar with a project will have a fundamentally different view of these issues than someone who is new to the project.

So let’s dive in.

Execution

There are five main things that I consider “execution” issues: language, interoperability, license, bug counts (or “quality”), and cost.

Language

Language choice definitely affects a project in a lot of ways. For one thing, if you have a Java-only project, using a library written in another language implies bringing in that language’s dependencies; it also implies that the other language has a different mindset at its core than your project.[3]

Interoperability

Interoperability is closely related to the concerns of language. A library that’s written in Scala has to be carefully designed to be properly usable from a Java class; some languages (Groovy, for example) focus on compatibility to maximize interoperability, but others require special concern. As a user of a library, you have to consider how easily you will be able to use it, regardless of how ideal the library looks otherwise.

Interoperability factors in even more heavily when you consider multiple languages: imagine a Java project using libraries written in both Scala and Clojure. If those libraries are not isolated from each other, you will have to make sure that the Scala and Clojure aspects don’t interfere with each other.[4]

Interoperability crosses many boundaries; a library that creates a Web service has to create artifacts consumable by other Web services that don’t use the same library.

License

License affects the circumstances under which you can use a library or tool. A license might affect whether you can use a tool at build time, or whether you can bundle it with your project’s artifacts, or under what circumstances you have to bundle library artifacts.

For example, you may be able to use a library for free in your commercial project – if you provide access to the library’s source. Alternatively, a license may preclude use in projects with incompatible licenses.

As a result, you have to consider the licenses of what you use constantly, and how those licenses interact with your chosen licensing scheme.

Sadly, this means interacting with lawyers in many cases, if you want to be sure the issues are clearly explained.

Bug counts (“quality”)

Another objective factor to consider is whether the library or tool is able to deliver what it promises.

For example, a library might have a stated goal of providing syndicated feeds of all sorts, but fail to deliver valid data for any format other than RSS 0.92. If you need ATOM or RSS 2.x or some other format, that library might be inappropriate for your use.

However, if you really do only need RSS 0.92 and the library is workable otherwise, it’s worth considering. (In the Real World where Real People have to do Real Jobs, choosing such a library would have many negative implications, because requirements change.)

License of the original project factors in heavily here. It’s possible that you could correct any bugs yourself; for a library written with an open license, you could use a “local fork” in your projects, or you could contribute a patch to the library[5].

Cost

It’s a common assumption that libraries are free, reinforced by a massive ecosystem of libraries offered through Apache, java.net, codehaus, and other such groups. However, this isn’t the case; obviously, commercial endeavors exist in the Java ecosystem. It’s unfortunate that commercial products get less consideration simply through being commercial products.[6]

Before you consider a given library, consider the impact that your project will have on your business. If you’re writing an application that is mission-critical, and therefore is fundamental in bringing in those millions of dollars you intend to deserve, it’s silly being penny-wise and pound-foolish; if a commercial project gives you the reassurance you or your customers need, and a free project does not, you’re better off spending the money on the commercial project.

You should evaluate your own risk, of course.[7] The key here is to understand the risks associated with a free product, if any, and how those risks affect product delivery or performance. Standards compliance helps mitigate risk, because compliance generally means that you can switch out dependencies if a particular product is insufficient for some reason in the future.

Conception

Representing the “soft side” of project development, conceptual issues are the easiest ones to get wrong. However, conceptual issues can often be the easiest to address, especially if you’re able to network with someone who is experienced with a given library.[8]

There are three main concerns in conceptual issues: a project’s prime use case, its documentation, and how it addresses issues as an ecosystem.

Prime use case[9], or Your user experience

This concept focuses on “what,” and “where.” What does the project do? Where does it do it? Can the answers to these questions be summarized in a single sentence?

If the answers are complex, then this represents an investment on your part to understand the project in question. That is not to say that it may not be worth the effort[10]; in fact, the opposite is often true. A Java EE container is too complex to summarize simply, and even “where does it run” is difficult to describe in today’s complex environments. Add the cloud to the container, and it gets worse.

But complex answers to “what” and “where” mean that you will have to learn about the projects before being able to accurately judge them.

Documentation

This concept focuses on “who,” “when,” how,” and “why.” As such, it’s very broad, and its breadth indicates that it’s very important.

It’s probably fair to say that poor documentation kills more libraries and tools than any other issue.

Documentation should address four questions:

• Who is it for? Who should use this library? Is the library targeted for end users, or for those who implement libraries for end users?[11]
• When should the library be used? Is there any group of tasks the library is especially well suited for, or tasks for which the library is inappropriate[12]?
• How does it work? Obviously, if your intent is to use something, you should have some direction as to how you should use it; what’s the “right way” to interact with the library? This should cover all of the features that the library provides, clearly organized and indexed.[13]
• Why does it work that way? Sometimes, a project has an overarching concept that governs its design and usage; aligning yourself with or understanding this concept can make using the library far easier or more effective (or, if you like, more bug-free.)[14]

The documentation for a project should be easily read. If you dive into the documentation and you’re lost, ask yourself why? Is it because you went to an advanced, exhaustive reference section when you need to understand basic concepts? Are the basic concepts highlighted in separate documents?

Using a library that doesn’t have clear, easy-to-use documentation is certainly possible, and we all can probably name a series of common libraries that have this failing. That said, think of how much more satisfying it would be if these projects had excellent documentation to go with the exhaustive references.

Anticipation of concerns

This concept addresses the things that the library or tool designers didn’t anticipate.

How does a project work with varying build tools? Is it dependent on a specific project flow? How can one adjust for different circumstances?

For example, a project for Java that provided poor integration with Maven’s build phases is going to have a considerable uphill battle when users depend on Maven, which is often the case. Do the implementers have a plan for addressing the situations when users go “outside the lines?” Is the library able to be extended for unanticipated circumstances[15]?

Conclusion

In the modern development world, it’s very difficult to develop a “real application” without reusing the work of others[16]. However, not all libraries and tools are of exceptional quality, and often such things are guided by an overall concept that may or may not be suitable for your use.

In order to evaluate suitability – which is likely to be more important than quality – you should look at a number of points: license and cost (the objective requirements), API consistency, dependencies, and whether the documentation is good enough for you to use, and whether the package you’re considering integrates with your processes well.

This isn’t to say that a tool or library that isn’t ideal in all of these areas should be avoided, necessarily – it may be that the package’s insufficiencies can be overcome and it’s all worth it in the end. Also, if you provide a tool or package yourself, perhaps these considerations can serve as a guide to helping improve overall quality and userbase.

comment on this article

In the end, you have to make your own decisions, based on your own criteria. Hopefully this article has given you some extra thoughts on how to identify the projects you want to work with.

04 Aug 2011