Best practices for multi-module project organisation

When setting up a maven project consisting of multiple modules there are multiple ways to define the project dependencies.

1. Use one top level directory containing only module subfolders. The parent/module-POM resides in it's own module subdirectory (e.g. project-parent)
2. Use one top level directory containing module subfolders  and the parent/module-POM.
3. Use one top level directory containing module subfolders and a POM file defining the modules of the project. The parent-POM resides in a submodule folder.

These are the three most common approaches to organize your project structure, each of which has it's own advantages and disadvantages.


Approach 1

Plus Side:

• Works well with IDEs like Eclipse

Minus Side:

• Hard to integrate with continous build systems because of the colocation of the definition of modules and the parent pom configuration. This makes standalone watchdog builds of modules almost impossible because the whole source tree is necessary to build a module.

Approach 2

Plus Side:

• Only one single top level POM to maintain.

 Minus Side:

• Hard to integrate with continous build systems because of the colocation of the definition of modules and the parent pom configuration. This makes standalone watchdog builds of modules almost impossible because the whole source tree is necessary to build a module.
• Top level POM is hard to integrate into project structures (e.g. eclipse) as it lies in a parent directory of the modules' project definitions.

Approach 3


Plus Side:

• Parent POM is easily defineable as project in your IDE
• Module definitions are separated from project configuration enabling the project to have multiple module set definition, e.g. have a definition to build only a subset of all modules - for impatient developers(like myself ;-)).
  
• Good integration with continuous integration systems because module definitions do not interfere with standalone module builds.

Minus Side:

• POMs containing module definitions may be difficult to integrate in IDE.

Conclusion


In my experience the third approach works best for most larger modules. Especially the compatibility with both IDEs and continuous build systems like Hudson make your work a lot easier.

So what does the recommended structure look like? Quite simple. You simply have a main directory that contains a top-level POM file and subdirectories for the parent module and submodules.

A sample minimal project can be downloaded from github (I guess I could make a Maven artifact for it but I just do not have the time right now).