Structure d’un projet Java : src, package, classpath

1. Dossier src — où vit votre code

Si un projet Java était une maison, le dossier src serait le salon chaleureux où se réunissent tous les habitants principaux (vos classes). C’est ici que l’on place tous les fichiers sources contenant du code, et non à la racine du projet, ni dans un dossier de configuration, ni sur le bureau (même si la tentation est grande).

Pourquoi séparer les sources du reste ?

• Le dossier src ne contient que les fichiers que vous écrivez vous‑même : .java.
• Tout ce qui apparaît lors de la construction (par exemple, les fichiers .class, les fichiers temporaires) est rangé dans d’autres dossiers (out, build, target, etc.).
• Cela facilite la navigation, rend le projet plus propre et rend l’IDE plus heureuse.

Exemple de structure d’un projet simple :

MyFirstProject/
├── .idea/           # fichiers de service d’IntelliJ IDEA, ne pas toucher
├── out/             # ici apparaissent les fichiers .class compilés
├── src/             # c’est ici que vit votre code source !
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Important :
Tout ce que vous écrivez vous‑même — classes, packages, interfaces — doit se trouver dans le dossier src. N’y mettez pas d’images, de musique ni de recettes secrètes — d’autres dossiers sont là pour ça.

2. Packages package

En Java, on regroupe les classes par « packages » — c’est comme des dossiers du système de fichiers, mais pour les classes. Les packages aident à :

• Éviter les conflits de noms si le projet contient deux classes Main — dans des packages différents elles ne se gênent pas.
• Structurer logiquement le code (par exemple, com.codegym.tasks, com.mycompany.utils).
• Gérer l’accès aux classes et aux méthodes.

Syntaxe de la déclaration de package

Au début de chaque fichier Java (avant tous les import et class), on écrit la ligne :

package com.codegym.lesson05;

Cela signifie : la classe de ce fichier appartient au package com.codegym.lesson05.

Important :
Les dossiers du système de fichiers doivent correspondre au nom du package ! Si vous avez écrit package com.codegym.lesson05;, alors le chemin du fichier sera :

src/com/codegym/lesson05/Main.java

Comment créer un package dans IntelliJ IDEA

1. Dans le panneau Project, cliquez avec le bouton droit sur le dossier src.
2. Choisissez New → Package.
3. Saisissez un nom, par exemple : com.codegym.lesson05 (l’IDE créera automatiquement les sous-dossiers).
4. Créez maintenant une nouvelle classe dans ce package. Cliquez avec le bouton droit sur le dossier com.codegym.lesson05 et sélectionnez New → Java Class. Puis saisissez le nom

Exemple :

src/
└── com/
    └── codegym/
        └── lesson05/
            └── User.java

Pourquoi ne pas simplement tout mettre dans src ?

Si vous mettez toutes les classes pêle‑mêle, le projet se transformera vite en « décharge », où trouver le bon fichier sera plus difficile que de trouver un chargeur d’ordinateur portable dans une résidence étudiante. Utilisez des packages — il sera plus simple de faire évoluer le projet, d’ajouter des bibliothèques tierces et de partager le code entre différentes équipes.

3. Nom complet d’une classe

Chaque classe en Java se trouve forcément dans un package. Un package est tout simplement un « dossier » à l’intérieur de la bibliothèque de classes. Par exemple :

• La classe System se trouve dans le package java.lang. Son nom complet est java.lang.System.
• La classe Scanner se trouve dans le package java.util. Son nom complet est java.util.Scanner.
• La classe ArrayList est également dans java.util, donc son nom complet est java.util.ArrayList.

Autrement dit, nom complet d’une classe = nom du package + point + nom de la classe.

Essayons de l’utiliser dans le code :

java.util.Scanner sc = new java.util.Scanner(System.in);
String name = sc.nextLine();
System.out.println("Bonjour, " + name);

Ici, nous écrivons explicitement java.util.Scanner. Le compilateur comprend de quelle classe il s’agit, même s’il y a d’autres classes nommées Scanner dans le programme.

C’est très important : le nom d’une classe peut coïncider, mais le nom complet est toujours unique.

Pourquoi a‑t‑on besoin du nom complet ?

Imaginez que nous ayons deux classes différentes Date :

• java.util.Date (ancienne classe pour la gestion des dates),
• java.sql.Date (date pour travailler avec les bases de données).

Si vous écrivez simplement :

Date d = new Date();

Le compilateur ne saura pas quelle Date vous souhaitez utiliser. Mais si vous écrivez le nom complet :

java.util.Date d1 = new java.util.Date();
java.sql.Date d2 = new java.sql.Date(System.currentTimeMillis());

— il n’y aura aucune confusion.

4. L’instruction import

Écrire à chaque fois le nom complet d’une classe n’est pas pratique. C’est précisément pour cela que Java dispose de l’instruction import.

Si nous écrivons :

import java.util.Scanner;

Cela signifie : « Dans ce programme, j’utiliserai la classe Scanner du package java.util ». Après cela, nous pouvons écrire simplement :

Scanner sc = new Scanner(System.in);

et le compilateur comprendra qu’il s’agit de java.util.Scanner.

Import classique (une classe)

C’est le cas le plus courant. Nous indiquons une classe précise :

import java.util.Scanner;
import java.util.ArrayList;

Vous pouvez maintenant écrire des noms courts : Scanner, ArrayList.

Importer tout un package *

Parfois, un programme utilise de nombreuses classes d’un même package. On peut alors écrire :

import java.util.*;

Cela signifie : « Autoriser l’utilisation de toutes les classes du package java.util sans nom complet ».

Vous pouvez maintenant écrire :

Scanner sc = new Scanner(System.in);
ArrayList<String> list = new ArrayList<>();

Mais il est important de se souvenir : import java.util.*; importe uniquement les classes du package java.util, et pas celles de ses sous-packages. Par exemple, la classe java.util.concurrent.ConcurrentHashMap n’y est pas incluse. Il faut l’importer séparément.

Ce qu’on ne peut pas faire avec import

• import ne peut pas être utilisé à l’intérieur d’une méthode — il s’écrit uniquement au début du fichier.
• import ne charge pas les classes en mémoire. Il indique seulement au compilateur où récupérer la classe.
• import ne peut pas remplacer le nom complet s’il existe deux classes de même nom.

5. Classpath — comment Java recherche vos classes

Le classpath est « l’itinéraire » que Java parcourt pour trouver vos classes lors du lancement du programme. On peut le voir comme une liste de dossiers où Java va chercher les fichiers .class (versions compilées de vos .java).

Par défaut, l’IDE ajoute elle‑même le dossier src (ou le dossier des classes compilées, par exemple, out/production/ProjectName) au classpath. Ainsi, si vous avez écrit une classe dans le package com.codegym.lesson05, Java la cherchera au chemin :

out/production/ProjectName/com/javarush/lesson05/Main.class

Comment fonctionne le classpath dans IntelliJ IDEA ?

• Lorsque vous lancez le programme via l’IDE, celle‑ci renseigne automatiquement le classpath nécessaire.
• Si vous exécutez le programme depuis la ligne de commande, vous devez indiquer explicitement le classpath à l’aide de l’option -cp ou -classpath.
• Toutes les classes de votre projet et des bibliothèques ajoutées doivent se trouver dans des dossiers figurant dans le classpath.

6. Organisation du code dans le projet

Une classe — un fichier

En Java, il est d’usage que chaque classe public soit dans un fichier séparé portant le même nom que la classe. Par exemple, si vous avez une classe Person, alors le fichier doit s’appeler Person.java.

Exemple :

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

Les noms de fichiers et de classes doivent correspondre

Si la classe s’appelle MySuperClass, alors le fichier doit être MySuperClass.java. Ce n’est pas un caprice, mais une exigence du compilateur Java. En cas d’inversion — vous obtiendrez une erreur à la compilation.

Où stocker les ressources (images, fichiers texte) ?

• Pour les ressources, on crée généralement un dossier séparé, par exemple resources ou res.
• Dans IntelliJ IDEA, vous pouvez ajouter un tel dossier via un clic droit sur le dossier : Mark Directory as → Resources Root.
• Le code Java peut accéder à ces fichiers via le classpath.

Exemple de structure :

MyFirstProject/
├── src/
│   └── com/javarush/lesson05/
│       └── Main.java
├── resources/
│   └── config.txt

8. Erreurs typiques liées à la structure du projet

Discordance entre la structure des dossiers et le package
Si le début du fichier indique package com.codegym.lesson05;, mais que le fichier se trouve dans src/Main.java, le compilateur affichera l’erreur "package does not exist" ou "class not found". Veillez toujours à ce que les dossiers correspondent au nom du package !

Discordance entre le nom du fichier et le nom de la classe
Si la classe s’appelle Person et le fichier — People.java, vous obtiendrez "class Person is public, should be declared in a file named Person.java".

Déplacement manuel de fichiers sans mise à jour du package
Si vous avez déplacé un fichier dans un autre dossier, mais oublié de modifier la ligne package, le programme ne se compilera pas. Faites‑le depuis le panneau Project de l’IDE — elle mettra à jour package automatiquement !

Ressources non ajoutées au classpath
Si vous stockez des fichiers (par exemple, des fichiers texte) en dehors du dossier resources et que vous n’avez pas marqué le dossier comme Resources Root, le programme ne pourra pas les trouver via le classpath.