Struttura di un progetto Java: src, package, classpath

1. Cartella src — dove vive il tuo codice

Se un progetto Java fosse una casa, la cartella src sarebbe il salotto accogliente, dove si ritrovano tutti gli abitanti principali (le tue classi). Proprio qui vanno messi tutti i file sorgente con il codice, non nella radice del progetto, non nella cartella con le impostazioni e non sul desktop (anche se la tentazione è forte).

Perché separare i sorgenti dal resto?

• Nella cartella src si conservano solo i file che scrivi a mano: .java.
• Tutto ciò che nasce durante la build (per esempio i file .class, i file temporanei) finisce in altre cartelle (out, build, target ecc.).
• Questo facilita la navigazione, rende il progetto più pulito e l’IDE — più felice.

Esempio di struttura di un progetto semplice:

MyFirstProject/
├── .idea/           # file di servizio di IntelliJ IDEA, non toccare
├── out/             # qui compaiono i file .class compilati
├── src/             # qui vive il tuo codice sorgente!
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Importante:
Tutto ciò che scrivi tu — classi, package, interfacce — deve stare nella cartella src. Non metterci immagini, musica o ricette segrete — per questo esistono altre cartelle.

2. Pacchetti package

In Java è prassi raggruppare le classi in «pacchetti» — sono come cartelle nel file system, solo per le classi. I package aiutano a:

• Evitare conflitti di nomi: se nel progetto ci sono due classi Main, in package diversi non si ostacoleranno a vicenda.
• Strutturare logicamente il codice (per esempio, com.codegym.tasks, com.mycompany.utils).
• Gestire l’accesso a classi e metodi.

Sintassi della dichiarazione del package

All’inizio di ogni file Java (prima di tutti gli import e delle class) si scrive la riga:

package com.codegym.lesson05;

Significa: la classe di questo file appartiene al package com.codegym.lesson05.

Importante:
Le cartelle nel file system devono corrispondere al nome del package! Se hai scritto package com.codegym.lesson05;, allora il percorso del file sarà:

src/com/codegym/lesson05/Main.java

Come creare un package in IntelliJ IDEA

1. Nel pannello del progetto fai clic con il tasto destro sulla cartella src.
2. Seleziona New → Package.
3. Inserisci il nome, per esempio: com.codegym.lesson05 (l’IDE creerà automaticamente le cartelle annidate).
4. Ora crea una nuova classe all’interno di questo package. Fai clic con il tasto destro sulla cartella com.codegym.lesson05 e scegli New → Java Class. Quindi inserisci il nome

Esempio:

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

Perché non conviene mettere tutto dentro src?

Se metti tutte le classi alla rinfusa, il progetto si trasformerà presto in una «discarica», dove trovare il file giusto sarà più difficile che trovare il caricabatterie del portatile in un dormitorio studentesco. Usa i package — sarà più semplice scalare il progetto, collegare librerie di terze parti e dividere il codice tra team diversi.

3. Nome completo della classe

Ogni classe in Java si trova necessariamente in un package. Un package è semplicemente una «cartella» dentro la libreria delle classi. Per esempio:

• La classe System si trova nel package java.lang. Il suo nome completo è java.lang.System.
• La classe Scanner è nel package java.util. Il suo nome completo è java.util.Scanner.
• La classe ArrayList è anch’essa in java.util, quindi il nome completo è java.util.ArrayList.

Quindi nome completo della classe = nome del package + punto + nome della classe.

Proviamo a usarlo nel codice:

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

Qui scriviamo esplicitamente java.util.Scanner. Il compilatore capisce di quale classe si tratta, anche se nel programma esistono altre classi chiamate Scanner.

È molto importante: il nome della classe può coincidere, ma il nome completo è sempre univoco.

Perché serve il nome completo?

Immagina di avere due classi diverse chiamate Date:

• java.util.Date (classe vecchia per lavorare con le date),
• java.sql.Date (data per lavorare con i database).

Se scrivi semplicemente:

Date d = new Date();

Il compilatore non capirà quale Date vuoi usare. Ma se scrivi il nome completo:

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

— non ci sarà confusione.

4. L’operatore import

Scrivere ogni volta il nome completo della classe è scomodo. Per questo in Java esiste l’operatore import.

Se scriviamo:

import java.util.Scanner;

Questo significa: «In questo programma userò la classe Scanner dal package java.util». Dopo di che possiamo scrivere semplicemente:

Scanner sc = new Scanner(System.in);

e il compilatore capirà che si tratta proprio di java.util.Scanner.

Import normale (una classe)

È il caso più comune. Indichiamo una classe specifica:

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

Ora si possono scrivere i nomi brevi: Scanner, ArrayList.

Import di tutto il package *

A volte il programma usa molte classi dallo stesso package. In tal caso si può scrivere:

import java.util.*;

Questo significa: «Permetti di usare tutte le classi del package java.util senza il nome completo».

Ora si può scrivere:

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

Ma è importante ricordare: import java.util.*; importa solo le classi del package java.util, ma non dei sottopacchetti. Per esempio, la classe java.util.concurrent.ConcurrentHashMap non è inclusa. Va importata separatamente.

Cosa non si può fare con import

• Non si può usare import dentro un metodo — si scrive solo all’inizio del file.
• import non carica le classi in memoria. Dice solo al compilatore da dove prendere la classe.
• import non può sostituire il nome completo se ci sono due classi omonime.

5. Classpath — come Java cerca le tue classi

Classpath è il «percorso» lungo il quale Java cerca le tue classi quando avvia il programma. Lo si può vedere come un elenco di cartelle in cui Java cercherà i file .class necessari (le versioni compilate dei tuoi .java).

Per impostazione predefinita l’IDE aggiunge da sola la cartella src (o la cartella dei class compilati, per esempio, out/production/ProjectName) al classpath. Cioè, se hai scritto una classe nel package com.codegym.lesson05, Java la cercherà al percorso:

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

Come funziona il classpath in IntelliJ IDEA?

• Quando esegui il programma dall’IDE, questa imposta automaticamente il classpath necessario.
• Se esegui il programma dalla riga di comando, devi specificare esplicitamente il classpath con il flag -cp o -classpath.
• Tutte le classi del tuo progetto e delle librerie collegate devono trovarsi nelle cartelle indicate nel classpath.

6. Organizzazione del codice nel progetto

Una classe — un file

In Java è consuetudine che ogni public-classe stia in un file separato, chiamato come la classe stessa. Per esempio, se hai la classe Person, il file deve chiamarsi Person.java.

Esempio:

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

I nomi dei file e delle classi devono coincidere

Se la classe si chiama MySuperClass, allora il file deve essere MySuperClass.java. Non è un capriccio, ma un requisito del compilatore Java. Se sbagli — otterrai un errore in fase di compilazione.

Dove conservare le risorse (immagini, file di testo)?

• Per le risorse di solito si crea una cartella separata, ad esempio, resources o res.
• In IntelliJ IDEA puoi contrassegnare tale cartella con un clic destro sulla cartella: Mark Directory as → Resources Root.
• Il codice Java può accedere a questi file tramite classpath.

Esempio di struttura:

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

8. Errori tipici nel lavorare con la struttura del progetto

Mancata corrispondenza tra struttura delle cartelle e package
Se all’inizio del file è scritto package com.codegym.lesson05;, ma il file si trova in src/Main.java, il compilatore genererà l’errore "package does not exist" o "class not found". Assicurati sempre che le cartelle corrispondano al nome del package!

Mancata corrispondenza tra nome del file e della classe
Se la classe si chiama Person e il file — People.java, otterrai "class Person is public, should be declared in a file named Person.java".

Spostamento manuale dei file senza aggiornare il package
Se hai spostato un file in un’altra cartella ma ti sei dimenticato di cambiare la riga package, il programma non verrà compilato. Fallo dalla finestra Project dell’IDE — aggiornerà il package automaticamente!

Risorse non aggiunte al classpath
Se conservi i file (ad esempio, di testo) fuori dalla cartella resources e non hai contrassegnato la cartella come Resources Root, il programma non riuscirà a trovarli tramite il classpath.