Hand pick the right software project for your situation

There are many software projects in the Java ecosystem; it is critical to be able to evaluate the suitability of a given library or tool.

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.


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


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 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 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].


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.


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.


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]?


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.

[1] The Java ecosystem is not only quite large on its own, but it’s growing, through the addition of libraries in Scala, Groovy, Ruby, Python, Clojure, and others, all of which offer interoperability to varying degrees with each other.
[2] You are printing my opinions out on paper, aren’t you? Perhaps you’re framing them on your wall, as well? No?
[3] For example, Java projects normally don’t concern themselves too much with concurrency issues, for better or for worse. A Scala library, however, is likely to factor in concurrency early and often, which can affect how the library is used; it might seem ironically verbose to a normal Java programmer.
[4] Meanwhile, a sizeable and knowledgeable portion of the readership is muttering curses to itself, curses that sound strangely like “OSGi!” referring to OSGi’s ability to isolate dependencies from other modules. For example, module ”A” could depend on Scala and reference a module providing the Scala library without affecting module “B,” which could do the same for Clojure. Note that I have not tried this, so it may or may not work the way I imagine; also, you can do this sort of thing with other module systems (including Java EE’s classloader hierarchy).
[5] If you can, contribute patches. This improves the community as a whole, gives you some street credibility, and eases your future use of the library, as you won’t have to constantly merge in local changes to the actual project source tree.
[6] Yes, this is a self-serving statement, since a company with a licensed product signs my paychecks.
[7] Did you think I was operating solely as a commercial shill? Of course I wasn’t, even though I am employed by GigaSpaces, a commercial enterprise with a distributed application platform suitable for all possible uses.
[8] Quick suggestions: start with TheServerSide’s discussion forums, or Stack Overflow, or irc://irc.freenode.org/##java, depending on your network access and how comfortable you are with live interaction. Look for a teacher and a friend, two things that are invaluable in life as well as development.
[9] I so wanted to call this “Optimal Prime Use Case,” with an image of a red and blue truck, but I couldn’t. I am just too barking Sirius.
[10] “Not worth the effort” probably is a sadly deserved evaluation for many projects.
[11] Consider JavaMail, a library that’s awful for end-users, but serves as excellent underpinnings for libraries that do cater for end users, like commons-email.
[12] I would love to see libraries point out situations in which they just don’t work, instead of providing endless justifications of ridiculous use cases.
[13] It’s easy to find violators of this concern. An example might be a “metal coil” project of some sort, which provides exhaustive documentation – which would be a good thing – except in a flood of information that’s not rapidly searchable, a bad thing. Not that any projects like this spring immediately to mind.
[14] Not that being bug-free matters.
[15] “Unanticipated circumstances” is a euphemism for “your application requirements.”
[16] It’s possible to develop a full application without external libraries, of course, because those external libraries use the basic core API. You could theoretically build everything yourself the same way. However, that’s a massive amount of work for most applications, and definitely isn’t worth the effort.


comment on this article

Dig Deeper on Java EE development and enterprise Java platforms

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.