Maven Tip: Project Directories Should Match the Artifact ID

January 28, 2011 By Tim O'Brien

I almost called this post a Maven “Pet Peeve”, but I’ll stick with “Tip” (and I’ll keep it brief). Here’s a new rule, and I’d really like to hear what the community thinks about this.

Here’s the rule:

Name your project’s directory after the artifactId of your project. It is much easier for everyone to quickly recognize and comprehend multi-module project structure, and it will more closely resemble the experience for developers working with IDEs.

Why do this?

Because it leads to simpler, easier to understand project structure. Some of you might be reading this and asking why we need to remind people of such an obvious rule. Others might take issue with the proposed rule, but I’ll try to detail why I think it is so important. Take the following collection of projects as an example:

Which one do you prefer? Left or right, and why?

On the one hand it is less typing for people on the command line to use simple directory names for Maven modules.

But, on the other hand, if you import these projects with m2eclipse you are going to end up with projects named after the artifactId. The same is true if you import these projects into IntelliJ.

I would suggest always opting for the option on the right. It is clearer than the alternative, and requires less hands-on investigation to track down a culprit project if you are debugging build errors.

An Important Note from Brian Fox: Naming the folder after the artifactId is critical if you expect inherited urls (scm/site) to work. It always appends the artifactId to the url as it’s inherited. And for the same reason, you want them to match what’s in the scm.

  • Vincent Massol

    One problem is that artifactIf are unique whereas directory names are supposed not to duplicate their parent names.

    For example imagine the following module directory:

    The pom.xml would have an artifactId of platform-core-action

    So you’d have a directory of: platform/core/platform-core-action

    Which is why I’ve always hesitated using artifactIds as directory names. I’m tempted to say it’s the best solution but I’ve always had this nagging feeling that it’s not a perfect directory name because of the duplication.

    I’m curious to hear what others think.

  • Jesse Glick

    What is your recommended best practice for in the POM, then? I have seen most projects just use some short label with no particular pattern; others use a “Project :: Subproject :: Component” hierarchical convention, or something like a localization of “groupId – artifactId”; once in a while someone uses a long phrase which would likely be better suited to .

    You mentioned Eclipse and IntelliJ imports. Currently the NetBeans integration – which loads the project natively, not using an import step – uses (rather than e.g. ) as the general-purpose display label for the project, which is consistent with its apparent purpose, as well as what is displayed most prominently in the CLI output. (Also in a large module tree, the is of course unique under a direct parent, but often not at all distinctive among all modules.)

    • Tim O’Brien

      Jesse, I consider free-form. I’ve seen people do different things with name, and half the time I’m working on projects people tend to just put garbage in both name and description. My general rule of thumb is to make sure that name is between an identifier and a description.

      On the Netbeans import for name instead of artifactId. I didn’t know that. Is that configurable? Also, people keep on telling me that Netbeans has great Maven integration. Even though Sonatype is focused on m2eclipse, I still try to do as much work as I can in IntelliJ just to make sure I’m not out of touch with people who use it. I guess I’ll have to add Netbeans to my list as well.

  • batmat

    For the record, after reading this article, I’ve created a small projet that contains a mojo designed to check that:

    Don’t hesitate to make feedback or feature requests.


  • Sri Sankaran

    The trouble is that Maven’s own archetyping mechanism falls short here. I cannot create a multi-module archetype that when used will produce a project whose sub-modules include the name of the artifact as a prefix.