Thursday, April 12, 2012

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.

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.  


Eric Kolotyluk said...

Very nice article. The trick is how to lead newbies to more articles like this before they hurt themselves with Maven.

If you enter 'maven' in Google search you most likely find and should soon find - but this page does not explain what this article does - and it should.

Asaf Mesika said...

Dude, I agree - Maven Docs suck, but If you spend the initial time to read the Maven Book, I think reading the Maven Plugin docs will be so much easier.

Unknown said...


There's a lively thread (14 posts) at

You should probably join in.

Andries Spies said...

I still want to see the convention part in maven. Any project beyond the most simplest quickly devolve into an exploision of xml configuration.

Chad Davis said...

@Andries Our build is definitely not simple, and we've been able to simplify it substantially by following conventions. However, I admit that the conventions are not easy to discover. That's why I'm going to blog about my experiences. I think I'll probably blog about the concept of attached artifacts next; it's the secret to letting maven manage all of our artifacts -- which is one of the more important conventions, the violation of which results in one of the largest explosions of xml.

Dusan said...

Thanks for your article!

I am currently struggling with exactly the same issues as you've described here - having read some maven books and worked with maven for quite a long time I seem to understand how individual parts of Maven work. What I am missing and looking for is information on how to assemble those parts into a whole to get smooth development process from the beginning to the very end.

When do you plan to publish the next article in this series?

Thanks a lot!

Chad Davis said...

Hi Dusan. I've had the draft of the next article nearly done for quite some time. Hopefully, I'll get it out in the next few weeks. Thanks for your feedback!

Unknown said...

Very well put and I couldn't agree more. Yours is a different take on how I typically introduce maven to engineers unfamiliar with it. I urge them to avoid learning too much from the "recipes" found in a lot of the docs and instead understand the build lifecycle that Maven implements and the project object model which is threaded through it. I think it is a steeper learning curve than hitting the ground running with a "hello world" pom since it requires them to think abstractly about software builds (as the Maven designers have) but it also helps a great deal when it comes to understanding why maven is doing what is is doing. All too often I encounter developers who keep a text editor open with all the "magical" commands which they need to recite to accomplish one build use case or another.

Chad Davis said...


I like your use of the term "magic". Magic is the historically related to early science; cause and effect without the logical connection. But incantations, eye of newt, and all of that stuff doesn't quite get the reproducibility that I want from my builds.