Estructura de un proyecto Java: src, package, classpath

1. Carpeta src — donde vive tu código

Si un proyecto Java fuera una casa, la carpeta src sería el salón acogedor donde se reúnen todos los habitantes principales (tus clases). Aquí es donde se colocan todos los archivos fuente con código, y no en la raíz del proyecto, ni en la carpeta de configuración ni en el escritorio (aunque te apetezca mucho).

¿Por qué separar el código fuente de todo lo demás?

• En la carpeta src se guardan solo los archivos que escribes a mano: .java.
• Todo lo que aparece durante el proceso de compilación (por ejemplo, archivos .class, archivos temporales) se coloca en otras carpetas (out, build, target, etc.).
• Esto facilita la navegación, mantiene el proyecto más limpio y hace más feliz a la IDE.

Ejemplo de la estructura de un proyecto sencillo:

MyFirstProject/
├── .idea/           # archivos de servicio de IntelliJ IDEA, no tocar
├── out/             # aquí aparecen los archivos .class compilados
├── src/             # ¡aquí vive tu código fuente!
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Importante:
Todo lo que escribes tú —clases, paquetes, interfaces— debe estar en la carpeta src. No pongas allí imágenes, música ni recetas secretas: para eso hay otras carpetas.

2. Paquetes package

En Java es habitual agrupar las clases en «paquetes»: es como las carpetas del sistema de archivos, pero para clases. Los paquetes ayudan a:

• Evitar conflictos de nombres; si en el proyecto hay dos clases Main, en paquetes distintos no se estorbarán.
• Estructurar lógicamente el código (por ejemplo, com.codegym.tasks, com.mycompany.utils).
• Controlar el acceso a clases y métodos.

Sintaxis de la declaración de un paquete

Al principio de cada archivo Java (antes de cualquier import y class) se escribe la línea:

package com.codegym.lesson05;

Esto significa: la clase de este archivo pertenece al paquete com.codegym.lesson05.

Importante:
¡Las carpetas en el sistema de archivos deben coincidir con el nombre del paquete! Si has escrito package com.codegym.lesson05;, entonces la ruta al archivo será:

src/com/codegym/lesson05/Main.java

Cómo crear un paquete en IntelliJ IDEA

1. En el panel del proyecto, haz clic con el botón derecho sobre la carpeta src.
2. Elige New → Package.
3. Introduce el nombre, por ejemplo: com.codegym.lesson05 (la IDE creará automáticamente las carpetas anidadas).
4. Ahora crea una clase nueva dentro de ese paquete. Haz clic con el botón derecho sobre la carpeta com.codegym.lesson05 y selecciona New → Java Class. E introduce el nombre

Ejemplo:

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

¿Por qué no se puede simplemente meter todo en src?

Si pones todas las clases mezcladas, el proyecto se convertirá rápidamente en un «vertedero», donde encontrar el archivo necesario será más difícil que encontrar el cargador del portátil en una residencia de estudiantes. Usa paquetes: así será más fácil escalar el proyecto, conectar bibliotecas de terceros y dividir el código entre distintos equipos.

3. Nombre completo de la clase

Cada clase en Java pertenece obligatoriamente a algún paquete. Un paquete es simplemente una «carpeta» dentro de la biblioteca de clases. Por ejemplo:

• La clase System está en el paquete java.lang. Su nombre completo es java.lang.System.
• La clase Scanner está en el paquete java.util. Su nombre completo es java.util.Scanner.
• La clase ArrayList también está en java.util, por lo que su nombre completo es java.util.ArrayList.

Es decir, nombre completo de la clase = nombre del paquete + punto + nombre de la clase.

Probemos a usar esto en código:

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

Aquí escribimos explícitamente java.util.Scanner. El compilador entiende de qué clase exacta se trata, incluso si en el programa hay otras clases llamadas Scanner.

Esto es muy importante: el nombre de la clase puede coincidir, pero el nombre completo siempre es único.

¿Para qué sirve el nombre completo?

Imagina que tenemos dos clases diferentes Date:

• java.util.Date (clase antigua para trabajar con fechas),
• java.sql.Date (fecha para trabajar con bases de datos).

Si simplemente escribes:

Date d = new Date();

El compilador no sabrá qué Date quieres utilizar. Pero si escribes el nombre completo:

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

— no habrá confusión.

4. El operador import

Es incómodo escribir cada vez el nombre completo de la clase. Precisamente para eso existe en Java el operador import.

Si escribimos:

import java.util.Scanner;

Esto significa: «En este programa voy a usar la clase Scanner del paquete java.util». Después de esto podemos escribir simplemente:

Scanner sc = new Scanner(System.in);

y el compilador entenderá que se trata de java.util.Scanner.

Import normal (una clase)

Es la variante más común. Indicamos una clase concreta:

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

Ahora se pueden escribir nombres cortos: Scanner, ArrayList.

Importar todo un paquete *

A veces en el programa se usan muchas clases de un mismo paquete. Entonces se puede escribir:

import java.util.*;

Esto significa: «Permitir usar todas las clases del paquete java.util sin el nombre completo».

Ahora se puede escribir:

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

Pero es importante recordar: import java.util.*; importa solo las clases del paquete java.util, pero no de sus subpaquetes. Por ejemplo, la clase java.util.concurrent.ConcurrentHashMap no quedará incluida. Hay que importarla por separado.

Qué no se puede hacer con import

• import no se puede usar dentro de un método: se escribe solo al principio del archivo.
• import no carga las clases en memoria. Solo le dice al compilador de dónde tomar la clase.
• import no puede sustituir el nombre completo si hay dos clases con el mismo nombre.

5. Classpath — cómo Java busca tus clases

El classpath es la «ruta» por la que Java busca tus clases cuando ejecuta el programa. Puedes imaginarlo como una lista de carpetas donde Java buscará los archivos .class necesarios (las versiones compiladas de tus .java).

De forma predeterminada la IDE añade por sí misma la carpeta src (o la carpeta de clases compiladas, por ejemplo, out/production/ProjectName) al classpath. Es decir, si has escrito una clase en el paquete com.codegym.lesson05, Java la buscará en la ruta:

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

¿Cómo funciona el classpath en IntelliJ IDEA?

• Cuando ejecutas el programa desde la IDE, esta establece automáticamente el classpath necesario.
• Si ejecutas el programa desde la línea de comandos, debes indicar explícitamente el classpath con la opción -cp o -classpath.
• Todas las clases de tu proyecto y de las bibliotecas añadidas deben estar ubicadas en carpetas incluidas en el classpath.

6. Organización del código en el proyecto

Una clase — un archivo

En Java se acostumbra a que cada clase public esté en un archivo separado, que se llame igual que la propia clase. Por ejemplo, si tu clase es Person, el archivo debe llamarse Person.java.

Ejemplo:

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

Los nombres de archivos y clases deben coincidir

Si la clase se llama MySuperClass, el archivo debe ser MySuperClass.java. No es un capricho, sino un requisito del compilador de Java. Si te equivocas, obtendrás un error en la fase de compilación.

¿Dónde guardar los recursos (imágenes, archivos de texto)?

• Para los recursos normalmente se crea una carpeta aparte, por ejemplo, resources o res.
• En IntelliJ IDEA puedes marcar esa carpeta con clic derecho: Mark Directory as → Resources Root.
• El código Java puede acceder a esos archivos a través del classpath.

Ejemplo de estructura:

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

8. Errores típicos al trabajar con la estructura del proyecto

No coincide la estructura de carpetas con el paquete
Si al principio del archivo pone package com.codegym.lesson05;, pero el archivo está en src/Main.java, el compilador mostrará el error "package does not exist" o "class not found". ¡Asegúrate siempre de que las carpetas correspondan al nombre del paquete!

No coinciden el nombre del archivo y el de la clase
Si la clase se llama Person y el archivo People.java, obtendrás "class Person is public, should be declared in a file named Person.java".

Mover archivos manualmente sin actualizar el paquete
Si has movido un archivo a otra carpeta pero olvidaste cambiar la línea package, el programa no se compilará. Hazlo en la ventana Project de la IDE: ella actualizará el package automáticamente.

Recursos no añadidos al classpath
Si guardas archivos (por ejemplo, de texto) fuera de la carpeta resources y no marcas la carpeta como Resources Root, el programa no podrá encontrarlos a través del classpath.