Java project structure: src, package, classpath

1. The src folder — where your code lives

If a Java project were a house, the src folder would be the cozy living room where all the main residents (your classes) gather. This is exactly where all source files with code go — not in the project root, not in a settings folder, and not on the desktop (even if you really want to).

Why separate source files from everything else?

• The src folder stores only the files you write yourself: .java.
• Everything that appears during the build (for example, .class files, temporary files) is placed in other folders (out, build, target, etc.).
• This makes navigation easier, keeps the project cleaner, and makes your IDE happier.

Example structure of a simple project:

MyFirstProject/
├── .idea/           # IntelliJ IDEA service files, do not touch
├── out/             # compiled .class files appear here
├── src/             # this is where your source code lives!
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Important:
Everything you write yourself — classes, packages, interfaces — must be in the src folder. Don’t put images, music, or secret recipes there — use other folders for that.

2. Packages package

In Java, it’s customary to group classes into “packages” — they’re like folders in a file system, only for classes. Packages help you:

• Avoid name conflicts if there are two Main classes in the project — they won’t interfere with each other if they are in different packages.
• Logically structure the code (for example, com.codegym.tasks, com.mycompany.utils).
• Control access to classes and methods.

Package declaration syntax

At the beginning of every Java file (before all import and class statements) you write a line:

package com.codegym.lesson05;

This means the class in this file belongs to the com.codegym.lesson05 package.

Important:
Folders in the file system must match the package name! If you have package com.codegym.lesson05;, then the path to the file will be:

src/com/codegym/lesson05/Main.java

How to create a package in IntelliJ IDEA

1. In the Project pane, right‑click the src folder.
2. Select New → Package.
3. Enter a name, for example: com.codegym.lesson05 (the IDE will create nested folders automatically).
4. Now create a new class inside this package. Right‑click the com.codegym.lesson05 folder and choose New → Java Class, then enter the name.

Example:

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

Why can’t you just put everything into src?

If you throw all classes together, the project will quickly turn into a “dump,” where finding the right file is harder than finding a laptop charger in a student dorm. Use packages — it will be easier to scale the project, add third‑party libraries, and split code among different teams.

3. Fully qualified class name

Every class in Java must be in some package. A package is just a “folder” inside the class library. For example:

• The System class is in the java.lang package. Its fully qualified name is java.lang.System.
• The Scanner class is in the java.util package. Its fully qualified name is java.util.Scanner.
• The ArrayList class is also in java.util, so its fully qualified name is java.util.ArrayList.

That is, the fully qualified class name = package name + dot + class name.

Let’s try using this in code:

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

Here we explicitly write java.util.Scanner. The compiler understands exactly which class we mean, even if the program has other classes named Scanner.

This is very important: class names can collide, but the fully qualified name is always unique.

Why do we need the fully qualified name at all?

Imagine we have two different Date classes:

• java.util.Date (the old date class),
• java.sql.Date (a date for working with databases).

If you just write:

Date d = new Date();

The compiler won’t know which Date you want to use. But if you write the fully qualified name:

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

— there will be no ambiguity.

4. The import statement

Writing a class’s fully qualified name every time is inconvenient. That’s exactly why Java has the import statement.

If we write:

import java.util.Scanner;

This means: “In this program I will use the Scanner class from the java.util package.” After that, we can simply write:

Scanner sc = new Scanner(System.in);

and the compiler will understand that we mean java.util.Scanner.

Single-class import

This is the most common option. We specify a single class:

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

Now you can use short names: Scanner, ArrayList.

Import the entire package *

Sometimes a program uses many classes from the same package. Then you can write:

import java.util.*;

This means: “Allow using all classes from the java.util package without the fully qualified name.”

Now you can write:

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

But it’s important to remember: import java.util.*; imports only classes from the java.util package, but not from subpackages. For example, the java.util.concurrent.ConcurrentHashMap class won’t be included. You need to import it separately.

What import cannot do

• You cannot use import inside a method — it’s written only at the top of the file.
• import does not load classes into memory. It only tells the compiler where to get the class from.
• import cannot replace the fully qualified name if there are two classes with the same simple name.

5. Classpath — how Java finds your classes

The classpath is the “route” Java uses to find your classes when it runs a program. You can think of it as a list of folders where Java will look for the necessary .class files (the compiled versions of your .java files).

By default, the IDE itself adds the src folder (or the folder with compiled classes, for example, out/production/ProjectName) to the classpath. That is, if you wrote a class in the com.codegym.lesson05 package, Java will look for it at the path:

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

How does the classpath work in IntelliJ IDEA?

• When you run a program through the IDE, it automatically provides the required classpath.
• If you run a program from the command line, you need to explicitly specify the classpath using the -cp or -classpath flag.
• All classes from your project and the connected libraries must be located in folders listed in the classpath.

6. Organizing code in the project

One class — one file

In Java, it’s customary that every public class is in a separate file named the same as the class itself. For example, if your class is Person, then the file should be Person.java.

Example:

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

File and class names must match

If a class is named MySuperClass, the file must be MySuperClass.java. This isn’t just a whim; it’s a requirement of the Java compiler. If you mix them up, you’ll get a compilation error.

Where to store resources (images, text files)?

• Resources are usually placed in a separate folder, for example, resources or res.
• In IntelliJ IDEA, you can add such a folder by right‑clicking it: Mark Directory as → Resources Root.
• Java code can access these files via the classpath.

Example structure:

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

8. Common mistakes when working with project structure

Folder and package structure mismatch
If the top of the file says package com.codegym.lesson05;, but the file is located at src/Main.java, the compiler will throw "package does not exist" or "class not found". Always ensure that folders match the package name!

File name and class name mismatch
If the class is named Person, but the file is People.java, you’ll get "class Person is public, should be declared in a file named Person.java".

Moving files manually without updating the package
If you move a file to another folder but forget to change the package line, the program won’t compile. Do this in the Project window in the IDE — it will update the package automatically!

Resources not added to the classpath
If you store files (for example, text files) outside the resources folder and don’t mark the folder as Resources Root, the program won’t be able to find them via the classpath.

1

Task

JAVA 25 SELF, level 5, lesson 4

Locked

Magic Pile of Stones 🤖🧑

Magic Pile of Stones 🤖🧑

Open

1

Task

JAVA 25 SELF, level 5, lesson 4

Locked

Battle with the Two-Headed Dragon 🐉⚔️

Battle with the Two-Headed Dragon 🐉⚔️

Open

1

Task

JAVA 25 SELF, level 5, lesson 4

Locked

Using the tool by its full address 🛠️

Using the tool by its full address 🛠️

Open

1

Task

JAVA 25 SELF, level 5, lesson 4

Locked

Handling two calendar systems: Time from different dimensions ⏳

Handling two calendar systems: Time from different dimensions ⏳

Open