IntelliJ IDEA in Practice: Your First Java Project, Compile and Run

IDEA is not "Notepad with colours". It is a machine that performs all the mechanical steps in order for you: save a file and it compiles; change a dependency and it fetches from a repository; press Run and it turns .java into .class, assembles the classpath, starts a JVM and calls main. This article covers three things: installing and finding your way around (the UI and six terms), getting something to run (project layout / SDK / run configuration), and spotting the moment the tool is lying to you (caches, encodings, red code, a greyed-out Run button).

After this article you should be able to answer:

• What are Project / Module / SDK / Artifact, and which one decides which JDK I use?
• When I press Run, what does IDEA do first, and what second? Which folder does the output land in?
• Why is red code not necessarily my fault? Why did the Run button suddenly turn grey?

IntelliJ IDEA is the most widely used IDE among Java developers. It ships in two editions, and choosing wrong adds pointless detours to your learning:

The conclusion is simple: the rest of this course involves heavy Spring work, so use Ultimate; if you are only learning Java syntax for now, Community is more than enough.

IDEA ships an official Chinese Language Pack. Install it via Settings → Plugins, search Chinese, then restart. An honest recommendation:

• While learning, a localized UI reduces the frustration of not finding menus
• But shortcuts, error messages and Stack Overflow answers are all in English, so in the long run the English UI pays off more
• A middle ground: start in your own language, and immediately note the English menu name for every unfamiliar concept

Beginners get lost in the pile of terms inside Project Structure. They actually form a chain from largest container to final product:

In one sentence: one Project can contain several Modules; each Module binds an SDK, references Libraries, may carry Facets, and finally produces an Artifact.

After creating a project, the root gains a .idea/ folder and a *.iml file, holding:

Should they be committed to Git? There is no single answer — it depends on the content:

• workspace.xml holds your personal window state, so it must be excluded; committing it causes daily conflicts
• misc.xml / *.iml may contain the JDK version and module dependencies, so they can be committed when the team wants consistency
• The easiest approach: ignore the entire .idea/ in .gitignore and let everyone regenerate it from Maven's pom.xml

IDEA never explains these nouns, yet each one maps to a concrete thing. Play a round: the left column is what you click in a menu, the right column is what it actually does — a wrong pick explains the gap on the spot:

Follow the wizard: File → New → Project, choose Java, pick "IntelliJ" as the build system (skip Maven for now to reduce variables), and choose JDK 17 or 21 from the dropdown — if the dropdown is empty you have no JDK yet; click Add SDK → Download JDK and let IDEA fetch one for you.

Once created, right-click the src directory, go New → Package (enter com.example.demo), then on the package New → Java Class (enter Hello), and write:

A small green triangle appears to the left of the line numbers; click it and choose Run 'Hello.main()', or just press Shift+F10. The Run window prints the result.

The first time you press Run, IDEA creates a "Run/Debug Configuration" for you, recording how to run this class. Open Run → Edit Configurations and you will see these key items:

Beginners think "Run means run the Java code", but IDEA first finishes the "compile" step behind the scenes. The full chain is:

1. Incremental compile: IDEA recompiles only the .java files you changed instead of everything, so the second run is always fast
2. Write bytecode: output goes to the output directory — out/ for a non-Maven project, target/classes for a Maven one
3. Class loading: a JVM starts and a ClassLoader reads the main class's bytecode
4. Run main: the JVM invokes the entry method and the program runs

This is the pair most often confused; keep them straight:

That last row of the table is the hardest one to notice yourself. This animation shows how two copies of your bytecode come to coexist — watch frame 5: what Run reads and what the shell reads may not be the same file:

There is also a real number hiding in IDEA's build: its builder runs in a separate process that gets 700 MiB by default. As the project grows and annotation processors pile on, the build output starts showing java.lang.OutOfMemoryError: Java heap space — note that it crashes in the build phase, while your program itself runs perfectly. Drag that number:

Build Project vs Rebuild is equally worth remembering:

• Build Project (Ctrl+F9): incremental, compiling only changed files — your everyday choice
• Rebuild Project: wipes all output and recompiles everything — use it only when you suspect a stale cache; slow but clean

Now spread that chain out as a single-step run. Six events on the left after you click Run, on the right the variables and the call stack as they change — pay attention to beats 2 and 4: the grey button in Section 11 comes from beat 2, and the package does not exist in Section 12 comes from beat 4:

Debugging is IDEA's real productivity engine. Press Shift+F9 to start in Debug mode — same effect as Run, except it stops at breakpoints.

Click in the gutter next to a line to place one; a red dot means the breakpoint is set. Then memorize this set:

Here is one rarely used but superb trick: while stopped you can double-click a variable in the Variables panel, press Enter, and change its value, then Resume. To test "what if this parameter were empty", you don't change and rerun the code — just change the value.

Real projects are almost always Maven projects. Open one with File → Open and pick the directory containing pom.xml; IDEA recognizes it as a Maven project and imports it automatically.

After import a Maven tool window appears on the right. A few frequent actions to know:

• Automatic sync: when pom.xml changes, a small icon appears at the top right prompting Reload; one click fetches the new dependencies
• Reload All Maven Projects: the refresh button at the top-left of the Maven panel, equivalent to re-reading all poms and re-resolving dependencies
• Yellow warnings: a yellow squiggle under a dependency usually means "this artifact is not in the local repo" or "the version is overridden by dependencyManagement"; hover for the explanation

The reverse reading matters just as much: every checkbox in File → New → Project ends up as a <dependency> in pom.xml. Tick them once and compare with the generated file, and you will know what IDEA wrote on your behalf — so that next time it writes nothing, you can do it yourself:

The fastest way to find a port hog is one command:

The first lab is the animated version of Section 4: how many steps sit between saving and a live process. "Compile output" shows how target/classes gets filled; "hot reload" shows why editing one string does not need a restart; "debug" maps the six moves from Section 5 onto what happens inside the process:

The second answers a more fundamental question: how does the JVM get your class into memory? The "class loading" step shows it resolving the fully qualified name (com.example.demo.Hello) into a path on disk — which is exactly where the Package ... does not correspond to the file path error in Section 12 comes from: a package name is not decoration, it is part of a path.

The third targets "my code is fine but it says class not found". On "ClassNotFoundException" you watch it walk each entry on the classpath; whenever target/classes is empty or stale, any java command ends up on this dead street:

The fourth prepares you for the next article: a Spring Boot startup has several more steps than a bare main. A Runner is Boot's hook for "do something once the app is up" (CommandLineRunner / ApplicationRunner), and the last experiment shows how to actually read that wall of text when startup fails:

The fifth lab covers the most infuriating class of problem in this chapter: works in the IDE, dies in the terminal — because the two are not using the same JDK at all. Open "who wins" to watch the shell walk PATH in order, then "several JDKs installed" to see IDEA's Project SDK and the terminal's java drift apart:

Time to type. This console is wired to the same in-browser kernel and every reply is computed there — start with lab idebuild build, then work down:

And keep this comparison in mind. The left column is what beginners do every day, the right column is the same task done correctly — the difference is not speed but whether the tool fools you:

A greyed-out Run triangle never means "IDEA is broken"; it means IDEA has decided pressing it would certainly fail. Pick the module state on the left and the SDK state on the right, and the panel tells you exactly where to click to recover:

That trap deserves a real stack to close it. Notice the guilty frame is not the top line, and not the Exception in thread sentence either:

Goal: reproduce and repair the three classic "IDEA tricked me" scenes.

Do these three things in order, writing one sentence of observation for each:

1. Put a conditional breakpoint on line 8 with condition i == 3, start with Shift+F9, and confirm it stops only on the fourth iteration.
2. Stopped at line 15, double-click result in the Variables panel, change it to 0, then Resume. Expected output: the second line prints result * 2 = 0 — proof that editing a value really changes execution.
3. With Evaluate Expression (Alt+F8), compute data.length + result without touching the code, then evaluate nums[0] outside the loop context and observe what exception surfaces.

Done when: you can say why a conditional breakpoint beats println debugging, and how changing a runtime value differs from editing code and rerunning.

Three small edits, each reproducing one frequent failure — the skill being practised is spotting which layer broke:

1. Keep package com.example.demo; but move the file to the root of src. You will observe IDEA complaining that the package does not match the path, and the "fully qualified name → disk path" mapping from the Section 10 lab breaking on the spot.
2. Delete the whole out or target directory, do not Build, and run java -cp target/classes com.example.demo.DebugLab from the terminal. You will observe ClassNotFoundException; one mvn compile or Ctrl+F9 restores it.
3. Turn off auto-save under Settings → Appearance & Behavior → System Settings, edit a print line without pressing Ctrl+S, then hit Run. You will observe IDEA's prompt, and why it synchronises changes to disk before compiling.

Tip: after variant 3 you will internalise that "save ≠ compile ≠ run" are three separate events.

Create a two-module Maven project that links this article with #2:

Requirements: ① import it with File → Open on the parent directory (not New Project) and confirm two modules appear in the Maven panel; ② leave a deliberate null dereference in lab-app's main and use an exception breakpoint (Run → View Breakpoints → Java Exception Breakpoints) so IDEA stops at the throw site instead of you stepping around looking for it; ③ add a CommandLineRunner printing one statistics line after startup; ④ run it once with Run and once with Debug and write down three concrete differences; ⑤ finally launch it manually from the terminal with java -cp and notice what IDEA had been assembling for you.

Acceptance checklist: mvn clean install is green; Debug halts exactly at the exception; the manual java -cp launch also works — meaning you genuinely know how that classpath was built.