Java 25’s compact source files and instance main methods (JEP 512) are fantastic for scripts and quick experiments. But as your program grows — adding tests, multiple types, or reuse from other files — it’s time to graduate to a regular class. The good news: the migration is almost entirely mechanical.

Let me walk you through it step by step.

1. Recognize When It’s Time to Migrate

Convert a compact file into a regular class when you notice any of these signs:

• The file exceeds ~100 lines or handles multiple concerns
• You need to reuse methods from other files
• You want to write unit tests targeting individual methods
• You’re introducing multiple top-level types (records, enums, nested classes)
• You need public API for other packages to consume
• You want to package the code into a JAR or deploy it

2. Start With a Compact Source File

Here’s a typical compact program we’ll migrate:

final String title = "Tip Calculator";

void main() {
    banner();
    double bill = 84.50;
    double tipPct = 0.18;

    double tip = tipAmount(bill, tipPct);
    double total = bill + tip;

    printLine("Bill",  bill);
    printLine("Tip",   tip);
    printLine("Total", total);
}

double tipAmount(double bill, double pct) {
    return round2(bill * pct);
}

double round2(double v) {
    return Math.round(v * 100.0) / 100.0;
}

void banner() {
    println("=== " + title + " ===");
}

void printLine(String label, double value) {
    println(String.format("%-6s: %8.2f", label, value));
}

Save it as TipCalculator.java and run with java TipCalculator.java.

3. The Mechanical Migration Steps

Follow these steps in order — none of them require rethinking logic:

Step 1: Wrap Everything in a Class Declaration

Add a public class ClassName { ... } around all your code. The file name must match the class name (TipCalculator.java → class TipCalculator).

Step 2: Restore Explicit Imports

Compact files auto-import java.base and expose top-level IO methods (println, print, readln). A regular class needs explicit imports or fully qualified calls.

Replace:

• println(...) → System.out.println(...)
• print(...) → System.out.print(...)
• readln(...) → use java.util.Scanner or java.io.Console

Step 3: Promote main to the Traditional Form

The classic entry point signature is:

public static void main(String[] args)

You have two options:

• Simplest: make main public static and add the String[] args parameter.
• Keep instance style: leave main as an instance method (still valid in Java 25) — but the traditional form is more familiar to most Java developers.

Step 4: Decide Which Members Stay Instance vs. Become Static

• Instance fields/methods → keep as instance members and create the object from main.
• Pure utility methods (no shared state) → mark static and call them directly from main.

Step 5: Add Access Modifiers Where Appropriate

• public for the class and main.
• private for internal helpers.
• Package-private (no modifier) for methods you may want to unit-test from the same package.

4. Two Migration Styles

Style A: Static-Method Class (Best for Utilities)

If your program is essentially a collection of pure functions, make everything static:

public class TipCalculator {

    private static final String TITLE = "Tip Calculator";

    public static void main(String[] args) {
        banner();
        double bill = 84.50;
        double tipPct = 0.18;

        double tip = tipAmount(bill, tipPct);
        double total = bill + tip;

        printLine("Bill",  bill);
        printLine("Tip",   tip);
        printLine("Total", total);
    }

    // ---------- domain logic ----------

    private static double tipAmount(double bill, double pct) {
        return round2(bill * pct);
    }

    private static double round2(double v) {
        return Math.round(v * 100.0) / 100.0;
    }

    // ---------- output helpers ----------

    private static void banner() {
        System.out.println("=== " + TITLE + " ===");
    }

    private static void printLine(String label, double value) {
        System.out.println(String.format("%-6s: %8.2f", label, value));
    }
}

Notes:

• The final field became private static final (a constant, conventionally uppercase).
• println(...) became System.out.println(...).
• Helper methods became private static.
• Compile with javac TipCalculator.java and run with java TipCalculator.

Style B: Instance-Based Class (Best for Stateful Programs)

If your program has meaningful state or you plan to inject configuration, prefer an instance-based design:

public class TipCalculator {

    private final String title;

    public TipCalculator(String title) {
        this.title = title;
    }

    public static void main(String[] args) {
        new TipCalculator("Tip Calculator").run();
    }

    public void run() {
        banner();
        double bill = 84.50;
        double tipPct = 0.18;

        double tip = tipAmount(bill, tipPct);
        double total = bill + tip;

        printLine("Bill",  bill);
        printLine("Tip",   tip);
        printLine("Total", total);
    }

    // ---------- domain logic ----------

    double tipAmount(double bill, double pct) {
        return round2(bill * pct);
    }

    double round2(double v) {
        return Math.round(v * 100.0) / 100.0;
    }

    // ---------- output helpers ----------

    private void banner() {
        System.out.println("=== " + title + " ===");
    }

    private void printLine(String label, double value) {
        System.out.println(String.format("%-6s: %8.2f", label, value));
    }
}

Notes:

• A constructor accepts title, enabling multiple configurations.
• main is a tiny bootstrap that instantiates the class and calls run().
• The domain methods have package-private access, making them easy to unit-test.

5. A Side-by-Side Comparison

6. Final Checklist

Before you consider the migration complete:

• File name matches the public class name.
• main method is public static void main(String[] args).
• All println / readln calls use standard System.out / Scanner APIs (or explicit import java.lang.IO; if you want to keep them).
• Access modifiers reviewed (public, private, package-private).
• Constants renamed to UPPER_SNAKE_CASE and marked private static final.
• Compiles cleanly with javac — no more relying on the source-launcher.
• Consider extracting records, enums, or helper classes into their own files.
• Add unit tests for the newly exposed methods.

Summary

Migrating from a compact source file to a regular class in Java 25 is a mechanical, low-risk refactor:

1. Wrap the code in public class Name { ... }.
2. Restore explicit imports and System.out calls.
3. Upgrade main to the traditional public static void main(String[] args) signature.
4. Decide between a static-utility style or an instance-based design.
5. Add proper access modifiers and constants.

The beauty of Java 25 is that you can prototype with a compact file and graduate to a full class only when the program actually needs it — no rewrites, just a scaffolding upgrade.

Java 25 makes it easier than ever to write small, focused programs without ceremony. Thanks to JEP 512: Compact Source Files and Instance Main Methods (finalized in Java 25), you can skip the enclosing class declaration entirely and still define multiple methods and fields in a single source file. This is perfect for scripts, learning exercises, and quick utilities.

Let me walk you through the best practices for organizing methods in these compact files.

1. The Basic Structure

A compact source file has an implicit top-level class. You just write your main method (instance-style, no static required) and add helper methods around it:

void main() {
    println("Welcome!");
    greet("Alice");
    println("Sum = " + add(3, 4));
}

void greet(String name) {
    println("Hello, " + name + "!");
}

int add(int a, int b) {
    return a + b;
}

No public class Foo { ... } wrapper is needed. The compiler generates it for you.

2. Put main First (or Make It Easy to Find)

For readability, keep the entry point at the top of the file so a reader immediately sees the program’s flow:

void main() {
    var user = askName();
    var total = computeTotal(10, 20, 30);
    printReport(user, total);
}

// --- helpers below ---

String askName() {
    return "Guest";
}

int computeTotal(int... values) {
    int sum = 0;
    for (int v : values) sum += v;
    return sum;
}

void printReport(String user, int total) {
    println("User : " + user);
    println("Total: " + total);
}

This mirrors how many scripting languages read: entry point first, details after.

3. Group Related Methods Together

When your file grows, cluster methods by responsibility and separate the groups with comment banners:

void main() {
    var nums = List.of(1, 2, 3, 4, 5);
    println("Sum      = " + sum(nums));
    println("Average  = " + average(nums));
    println("Uppercase: " + shout("hello"));
}

// ---------- Math helpers ----------

int sum(List<Integer> xs) {
    return xs.stream().mapToInt(Integer::intValue).sum();
}

double average(List<Integer> xs) {
    return xs.stream().mapToInt(Integer::intValue).average().orElse(0);
}

// ---------- String helpers ----------

String shout(String s) {
    return s.toUpperCase() + "!";
}

If a group becomes large, that is a strong signal it should be extracted into its own class or file.

4. Use Instance Fields for Shared State

Compact files support instance fields, so you don’t need to pass configuration through every method call:

final String appName = "DemoApp";
final int maxRetries = 3;

void main() {
    banner();
    run();
}

void banner() {
    println("=== " + appName + " ===");
}

void run() {
    for (int i = 1; i <= maxRetries; i++) {
        println("Attempt " + i);
    }
}

Prefer final fields to keep the file predictable and easy to reason about.

5. Leverage the Auto-Imported java.base and IO Methods

Java 25 auto-imports common utilities and gives you top-level print, println, and readln (from java.lang.IO). This keeps helper methods short:

void main() {
    var name = readln("Your name: ");
    println(greeting(name));
}

String greeting(String name) {
    return "Hello, " + (name.isBlank() ? "stranger" : name) + "!";
}

No import statements, no System.out.println — the file stays compact.

6. Keep Methods Small and Single-Purpose

Because there is no class boundary to hide behind, discipline matters more. Follow these guidelines:

7. Order Methods by “Newspaper Style”

Arrange methods so the reader moves from high-level to low-level, like a newspaper article:

void main() {           // headline: what the program does
    processOrder();
}

void processOrder() {   // section: main steps
    validate();
    charge();
    ship();
}

void validate() { /* ... */ }   // details
void charge()   { /* ... */ }
void ship()     { /* ... */ }

Readers rarely need to jump around — they simply scroll down for more detail.

8. When to Stop Using a Compact File

Compact source files shine for small, self-contained programs. Migrate to a regular class (or multiple classes) when you notice:

• Multiple unrelated groups of methods
• Need for multiple types (records, enums beyond simple helpers)
• Reuse from other files
• Unit tests targeting individual methods

You can promote a compact file by simply wrapping everything in public class Name { ... } and adding public static void main(String[] args) — the migration is mechanical.

Complete Example

Here is a compact file that puts all the tips together:

final String title = "Tip Calculator";

void main() {
    banner();
    double bill = 84.50;
    double tipPct = 0.18;

    double tip = tipAmount(bill, tipPct);
    double total = bill + tip;

    printLine("Bill",  bill);
    printLine("Tip",   tip);
    printLine("Total", total);
}

// ---------- domain logic ----------

double tipAmount(double bill, double pct) {
    return round2(bill * pct);
}

double round2(double v) {
    return Math.round(v * 100.0) / 100.0;
}

// ---------- output helpers ----------

void banner() {
    println("=== " + title + " ===");
}

void printLine(String label, double value) {
    println(String.format("%-6s: %8.2f", label, value));
}

Run it directly with:

java TipCalculator.java

Summary

• Put main first, helpers below.
• Group related methods and separate groups with comment banners.
• Use instance fields for shared, mostly-final state.
• Rely on auto-imports and top-level IO methods to stay concise.
• Follow newspaper order — general to specific.
• Graduate to a regular class once the file grows beyond a single concern.

Compact source files let you write real, multi-method programs with almost zero boilerplate — as long as you keep the file focused and well-organized.

Java 25 finalizes JEP 512: Compact Source Files and Instance Main Methods, which was previewed in earlier JDK releases. This feature makes Java far more approachable for beginners and reduces boilerplate for small programs and scripts.

What Changed?

Traditionally, every Java program required this ceremony:

public class HelloWorld {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}

With Java 25, the main method no longer needs to be:

• public
• static
• Declared with a String[] args parameter

The New Rules

The JVM launcher now looks for a main method in this order of preference:

1. static void main(String[] args) — traditional form
2. static void main() — no parameters
3. void main(String[] args) — instance method with args
4. void main() — instance method, no args simplest form

If an instance main method is found, the JVM will implicitly create an instance of the enclosing class using its no-argument constructor, then invoke main on it.

Example 1: The Simplest Instance main

public class Hello {
    void main() {
        System.out.println("Hello from an instance main!");
    }
}

That’s the entire program. No static, no String[] args, no public.

Run it with:

java Hello.java

Example 2: Instance main With Fields and Helper Methods

Because main is now an instance method, it can freely use instance fields and call other instance methods without needing static everywhere:

public class Greeter {
    private final String greeting = "Hello";

    void main() {
        greet("Java 25");
        greet("Developers");
    }

    void greet(String name) {
        System.out.println(greeting + ", " + name + "!");
    }
}

Notice that greet is also a plain instance method — no static modifier needed.

Example 3: Combined With Compact Source Files

Java 25 also allows you to omit the enclosing class entirely (Compact Source File):

void main() {
    System.out.println("No class declaration required!");
}

Save this as Demo.java and run:

java Demo.java

The compiler implicitly wraps the code in a synthetic class for you.

Example 4: Instance main With Arguments

If you still need command-line arguments, just declare them:

public class Echo {
    void main(String[] args) {
        for (String arg : args) {
            System.out.println("Argument: " + arg);
        }
    }
}

Requirements & Caveats

• The enclosing class must have an accessible no-argument constructor (the default one is fine if you don’t declare any constructor).
• The class cannot be abstract.
• If both a static and an instance main exist, the static one wins (per the resolution order above).
• The instance main method cannot be private. It must be at least package-private.
• To run a single source file directly (java Foo.java), you don’t need to compile first — the launcher handles it.

Why This Matters

• Lower barrier for beginners — no need to explain public, static, String[] args, or classes on day one.
• Cleaner scripts — small utilities and experiments become much more concise.
• Smoother learning curve — students can gradually introduce classes, static, and access modifiers as they progress, rather than all at once.

Quick Comparison

Instance main methods, combined with compact source files, make Java 25 one of the most beginner-friendly releases in the language’s history — while remaining fully backward compatible with every existing Java program.