Java: Multiple class declarations in one file

java

best-practices

class-organization

java-11

byNikita Barsukov·Nov 15, 2024

In Java, a single file can house multiple classes; however, only one of them can be specified as public and the name of the file should correspond with this class. The other classes are package-private, meaning they cannot be accessed beyond the file they're declared in. This is how it typically would look:

public class MainClass { // Name me after file, or the compiler gets upset!
    // Main public class code.
    public static void main(String[] args) {
        // Coding party starts here 🎉
    }
}

class AuxiliaryClass { // Not for the public eye, I'm a shy class.
    // Auxiliary class code.
}

// You can have as many non-public classes like me, but remember we all like our space!

Bear in mind, AuxiliaryClass and any further classes aren't visible externally. They prefer to stay huddled within the file's boundary.

Best practices for class organization

Although Java doesn't restrict you from hosting a small army of classes in a single file, for the sake of sanity and organization, it's always advised to have one top-level class per file. Here's why:

Build process: When classes start playing hide-and-seek in your files, you're setting yourself up for a compilation nightmare. Keeping to one class per file promotes neatness and predictability.
Troubleshooting: Use the -Xlint:all flag during compilation to catch any class referencing alerts.
Staying Updated: Be aware of Java version specifications, especially when dealing with class referencing; Java 11+ has eased these restrictions but always double-check!

Embrace nested classes

Don't mistake the one top-level class rule for a ban on multiple data types within a file. Meet the nested or inner classes:

Closeness: Helper classes related to the main public class can be nested, ensuring related code sticks together like bees in a hive.
Privacy Respect: Nested classes can mingle with the outer class's private members, offering stronger data protection.

Leveraging Java 11 improvements

With Java 11, you're allowed to run .java files comprising multiple top-level classes thanks to JEP 330:

The main method must be a guest in the first class mentioned in the list.
Only one class can say 'I'm public' if you're using compilation.
While this feature is great for small scripts, larger applications must approach it with caution.

Understanding non-public top-level classes

When dealing with multiple classes in one file, take note:

They're commonly referred to as non-public top-level classes.
Think of these classes as hermits – they don’t like to be referenced from outside their file. They keep to themselves, avoiding namespace pollution and keeping your code neat.
It's a good idea to keep these classes minimal and to provide services specifically for your public class' needs.

Overcoming potential issues

Implementation of multiple class declarations may present a few challenges:

Ambiguous references: When two files declare a package-private top-level class with the same name, the compiler might suffer an existential crisis trying to resolve references, thereby spitting out errors.
Refactoring hurdles: Dividing and relocating classes can be tricky when there are a bunch of intertwined classes in the same file.
Navigation hiccups: It might prove difficult to find a needle-class in a haystack-file, especially when dealing with large projects.

Mitigation strategies:

Make friends with your IDE's navigation tools to quickly find class names.
Practise refactoring techniques diligently. When classes grow too big for their boots, split them into separate files.
Conscious and watchful management of class scope and access to uphold code modularity.

explain-codes / Java / Java: Multiple class declarations in one file

Linked

What causes and what are the differences between NoClassDefFoundError and ClassNotFoundException?



Access restriction on class due to restriction on required library rt.jar?



How do I hide .class files from the Open Resource dialog in Eclipse?



Why can outer Java classes access inner class private members?



Are there any Java method ordering conventions?

