Project Structure

Below are some answers to your question. You may also want to take a look at the following thread where similar questions are asked and answered in depth:

• http://devnet.jetbrains.com/message/5459805

After reading for a while i understood the relation between workspace and project, then between project and modules.

To be technical, IntelliJ IDEA does not really have a concept of a workspace, at least not by name. You have a project that has one or more modules. The project simply resides in a directory on the file system. You could consider that "area" on the file system a workspace.

when you create a project there is an initial module which to a certain extend is equivalent to the Project itself. To be more precise, the initial module folder is the Project folder. . . . My first question is what is the rationale of making this first module equivalent to the project folder ?

This is simply because the "Java" project wizard is for creating a simple single module project. As such, the module it creates exists at the project level. In general, you will not want to use this particular wizard to create your projects if you know (or even suspect) it will need to be multi-module project. Instead, there are other wizards or import options for creating a project.

To create a multi-module project from scratch, in the New project wizard, select "Empty project" that you mention. After creating the project (and opening it) IDEA will open the "Project Structure" dialog. Now go in an add modules to your project. With the "Modules" pane selected on the left, click the add button and then select the module type (such as Java). Typically you will create a module directory in the project root directory as you create the new modules (like you comment on in your question). The typical structure is:

project-root
+--module-1
|  +--src
|  +--module-1.iml
+--module-1
   +--src
   +--module-2.iml

If you have a multi-module maven project (for example that you checked out from source control), you can simply use File > Import Project then select the parent/root pom.xml file in the file chooser and click OK. (This is the way I create 99% of my projects. Even if creating from scratch, I create a very basic POM file, import it, and then start adding maven modules.) Gradle should work in a similar way. But I have not played with it much. If you have a multi-module project checked out from src code, you can use File > Import Project to import a project from existing source. Just select the root directory. IDEA will discover the sources in the sub-directory and give you the option to create a module for each.

I saw that one can start an empty project and then add modules to it. However in that case, the modules added are added as subfolder of the Project and therefore there is no initial module equivalent to the Project folder ? So why this difference and what is the rationale behind it ?

It's simply a matter if you want to create a single, or a multi-module project. Also, you don't have to add a module as a subfolder. That's just the typical way. I could create a module in the project root directory (I personally can't really think why one woulld want to, but someone might have a use case for it.) I could even create a module in a totally different directory tree (or different hard drive). Again, that would be a bit crazy, but it is possible.

What would be the better approach, the first or second ?

In general, the second (i.e. use the empty project option). The first (a single module project) only makes sense for simplistic hello world or other toy projects.

Would it be ok to have this first initial module with no src or test folder but just with the proper facet so as to spread it to the sub-module?

IDEA really does not have the concept of a "sub-module". While on a file system, you may have a module's root contained in another module's directory (see below), the settings of the "parent" module are not applied to the one contained in a sub-directory, So you need to add the facet to all the modules.

Following this, i would further ask, what the point of having modules as sub-module of others.

In most cases, you likely would not have this. You could however have them for something like, for example, a "UI" module (that likely has no code) to group together the "UI-REST", "UI-GUI" and "UI-Mobile" sub modules. In the case of maven, the "UI" module would have a packaging of type 'pom' and the others 'jar' or 'war'.So you would have something like this:


The advantage of the "UI" module is that I could define common dependencies (used by all the UIs in there) and have each child module inherit the UI dependencies. But this could also be done in a flat structure. It's purely personal preference of hierarchy vs flat structure:


Again, just a matter of preferences. Some people like a flat structure, others a hierarchical structure. Note that IDEA also has the concept of module groups that (only) adds hierarchy in the IDEA UI display (and note alter their locations on the file system). So in the case of the second (flat) configuration, I can orgaize the modules to a Higherarchy via module groups in the Project Structure dialog: Something like this:



Converting a single module project to a multi-module project
While you generally will want to create a multi-module project from scratch (see below), if you find the need to convert a simple single module project you can do the following. Unfortunately, to the best of my knowledge (10+ years of using IntelliJ IDEA), there is not a direct way in the UI to move a module. The below works. It's looks like a lot, but that's because I broke it down into very fine steps. In reality, it's quite straight forward. You ultimately are just temporarily removing the module from the project, moving it on the file system, then adding it back to the project.

1. Open the Project Structure dialog (Ctrl+Alt+Shift+S or File > Project Structure)
2. Select the 'Modules' pane on the left
3. Select the (default) module in the middle pane and click the delete button
   • This will only delete the module from the project configuration. No files will be deleted
4. Click Apply on the Project Structure Dialog.
5. On the file system, create a module directory (of any name) in the project root directory
6. Move the 'src' directory, the "module-name.iml' file (this is the module configuration file) into the module directory. Also move any other source/resource directories and files. You can move or delete the 'out'/'target' directory if present. Do not move the .idea directory (the project configuration) or if not using a directory based project configuration, the *.ipr or *.iws file.
7. In the project Structure dialog, still on the modules pane, click the add button and select "import module"
8. In the file chooser, navigate to the directory  you created and select the *.iml file.
9. If desired, rename the module at the top of the left pane (this will also rename the *.iml) file. You can name it the same as the module's directory (that you created); that is a typical configuration.
   
10. Click Apply on the project structure dialog.
11. Add/create additional modules as desired. (See below)
12. After closing the project structure dialog, you will need to update any run/debug configurations. You will need to set the module for the "use classpath of module" option and may have to modify the "working directory" to the module directory if desired.

Super Super Usefull. Appreciated