Maven Does Not Suck . . . but the Maven Docs Do

I'm not going to go into the whole Maven debate, but suffice it to say that I'm a strong proponent of everything best practice, and, to me, Maven is an embodiment of best practice. By this I mean that Maven is built around a specific best practice build methodology. Note, I said a specific best practice build methodology. In the real world, there are more than a handful of build methodologies that could qualify for the best practice accolade, but Maven assumes a single one of them. This does not mean that the others are not good, it just means that if you use Maven, you going to need to buy-in to the conventions it assumes . . . or suffer. This is true for any Convention Over Configuration ( CoC ) tool, and Maven is pretty darn  CoC.

Maven, like all design patterns, is a reuseable solution to the process of building software

I think the occasionally discussed notion of Maven as a design pattern for builds is a powerful metaphor.  It's useful because it emphasises that Maven, like all design patterns, is a reuseable solution to the process of building software.  It's a best practice solution that has been refined by a community of smart people over years of heavy use.  The most obvious benefits of leveraging a design pattern for building software are the same as those for writing software.  Namely:

• You get a bunch of functionality with out having to write it yourself
• An engineer that understands the pattern as applied to one project, can instantly understand the pattern as applied to another project.

Nominally, the first bullet is about productivity and and the second is about simplicity. Obviously, everybody wants to be more productive, i.e. accomplishing more with less lines of code. But, I actually think the second point -- simplicity -- is far more important. In my opinion, the entire field of engineering boils down, most elegantly, to the concept of "managing complexity". By complexity, I refer directly to that headache you get when bombarded with piles of spaghetti code.  Design patterns help eliminate this intellectual discord by sealing off a big chunk of complexity in a higher level notation.  In case you've forgotten, this is what frees our minds up for the bigger and cooler tasks that inevitably reside on the next level.

It is this point of view that makes me rank learning a new project's ad hoc build to be one of the most annoying aspects of my profession. Even if an ant or make build is very cleanly implemented, follows a localized best practice, and automates a broad scope of the software lifecycle, it still punishes  new developers with a mountain of raw data, i.e. lines of scriptcode. Note, it's only the ad hoc-ness that is a problem here. This is certainly not a knock on these tools. ant in particular is very good at automating your tasks and providing a reusable set of build widgets. But it does nothing to provide a reusable solution to the entire process of building software, and, accordingly, it does nothing to ease a new developers on their road to comprehending the build.

it's the conventions that matter most with a CoC tool like Maven

So, as I see it, it's the conventions that matter most with a CoC tool like Maven.  You have to know and follow the assumed conventions in order to be successful with Maven. Projects that don't follow the conventions quickly run afoul of Maven. First, they struggle to implement their own build process with a tool that assumes a build process of it's own. It's easy to fall into being upset that you can't easily do what you've been doing, but the preceding paragraphs are meant to suggest that it's actually you who needs to change, at least if you plan to continue on with Maven. When you choose Maven, you need to accept the conventions. I you can't, I suggest you stick with Ant, which is flexible enough to meet you on your terms. Just remember that you are losing the ability to leverage the design pattern aspect of Maven to manage the complexity of your build. And if you think your build doesn't have complexity issues, ask your self these questions:

• Can every engineer on our team easily build all the components of our software system?
• Do our engineers have the confidence to modify build scripts without angst?
• Do our engineers flee the room when someone is needed to address a build problem?

So, if you're with me so far, you'd probably agree that following the conventions assumed by Maven is a critical prerequisite for entering Maven nirvana. And this is what leads me to the conclude that the Maven docs suck.  They are not only inadequate, but perhaps detrimental; they mostly document the configuration while utterly failing on the critical topic of conventions.  The emphasis on configuration, which I assume is largely by accident, leads newbies into thinking it's okay, and perhaps even  normal, to configure Maven.

The Maven documentation is not only inadequate, but perhaps detrimental; it mostly documents the configuration while utterly failing on the critical topic of conventions.

By documentation, I mostly mean all that stuff you find when you visit the Maven or Codehaus plugin pages. For instance, consider the extremely core maven-assembly-plugin.  Browse through the docs on the Maven site and you'll find that it's almost entirely about configuration. The problem, as I've stated and restated, is that you don't really want to configure Maven; you want to follow the conventions. Configuration should be only an option of last resort.

plugin puts things and then the next plugin can't find that stuff.  Use a profile to tell Maven where to find something, and then nothing else can find that thing without the profile.  Configuring Maven gets you into a bit of a configuration feedback loop, and geometric growth of configuration does not lend itself to pom readability.  Even if you can get Maven to do what you need by configuring it to death, you quickly get an incomprehensible build.  

Use the configuration to change where one plugin puts things and then the next plugin can't find that stuff.

So, avoid configuration!  Stick instead to the conventional path. Your engineers will know and love their build, and you will easily leverage the many benefits offered by the Maven ecosystem -- from the rich plugin libraries to the repository servers and build servers.  

But how does one go about learning the Maven conventions?  It's all about community. Luckily, it's a pretty friendly community.  Here are some of the most important resources that I use when trying to determine how things should be done in Maven.

• Sonatype Blog
• Stackoverflow
• Maven Users List

Additionally, in an effort to be a friendly community member, I'm using this blog entry as an introduction to a series of Maven entries.  Each of these entries will outline important Maven conventions. I'll detail the convention as well as offer example poms.  So, keep in touch if you want to learn about Maven conventions.