Why is each public class in a separate file?

Question

I recently started learning Java and found it very strange that every Java public class must be declared in a separate file. I am a C# programmer and C# doesn't enforce any such restriction.

Why does Java do this? Were there any design considerations?

Edit (based on a few answers):

Why is Java not removing this restriction now in the age of IDEs? This will not break any existing code (or will it?).

Gadabout

IMHO, probably the worst design decision in the history of computing was for Java to force the file to class mapping. – Mardis

@Neil - That's a bit harsh. Have you used Lotus Notes? – Dumond

@oxbow_lakes: You made me curious..What has this to do with Lotus Notes? – Contumacy

Dupe: #968847 – Thicken

@oxbow As it happens, yes. I've also programmed it and ccMail, and while neither would ever be my favourite tools, I found them to have a suprisingly well designed API, if iI remember correctly (it was a while back) – Mardis

@Andre - well, when I hear the phrase "Worst design decision in the history of computing", Lotus Notes just springs to mind. – Dumond

@sandbox I agree this is not a dupe, and I think this is an interesting question, though one that can't really be answered except by Mr Gosling. It should probably therefore be CW. – Mardis

Even in C# it's usually considered a bad idea to have more than one top-level type in a file, unless they're delegates. – Maimaia

@jon how about classes derived from EventArgs? If only one particular class is using it to send as args then why not have it in same file? – Gadabout

@Jon Skeet I can't speak for C#, but in C++ there is no such opinion. Multiple related classes in the same file make a lot of sense. – Mardis

@Neil: I couldn't disagree more, and my view is the reason my C++ code builds faster than others. Not. Even. Close. – Begone

@280Z28 So #including more files speeds up your build process? Interesting. – Mardis

@Neil: No, including fewer files speeds up the build process. The idea is never introduce a semantic dependency chain that is unnecessary for compiling code element X. I found this can be accomplished with maximum impact at a per-class granularity. It also allows you to keep the GCC PCH size under 70mb on large projects, as you go past that you take a rather remarkable performance hit compared to its "sweet spot" (though this is far from the only place it impacts). – Begone

@280Z28 I don't see how your second comment backs up the first. But SO comments are not the ideal form for discussions like these - perhaps you could expand your ideas in a community wiki question? – Mardis

@Neil, ibitially I found this annoying, but after using Java a_lot_ I found that this convention helps a lot when working with other People's code! You have a lot less of Gjessing to dó which is really Nice! – Longwise

Answer 1

According to the Java Language Specification, Third Edition:

This restriction implies that there must be at most one such type per compilation unit. This restriction makes it easy for a compiler for the Java programming language or an implementation of the Java virtual machine to find a named class within a package; for example, the source code for a public type wet.sprocket.Toad would be found in a file Toad.java in the directory wet/sprocket, and the corresponding object code would be found in the file Toad.class in the same directory.

Emphasis is mine.

It seems like basically they wanted to translate the OS's directory separator into dots for namespaces, and vice versa.

So yes, it was a design consideration of some sort.

Detector

Does anyone have experience of using Java on platforms that don't have tree-structured directores? Perhaps someone that works on something like VM/CMS (or maybe it does have tree structures now - last time I used it was about 1988) could comment? – Mardis

Or I would say when they develop Java they are lazy :) – Enrage

@Neil: Visual Age didn't store its files in the file system, but in a (proprietary) Database instead. It still presented your classes hierarchically, due to the package system however. – Unimproved

You know, from the effect this consideration had, I think it does totally enforce programmers to rethink about coupling code. People who DON'T think it's a good idea to write their classes, as in at least one-file-per-public-class-basis, obviously haven't been on large projects long enough to get fed up with rereading large code files just to change "that small thing" (or are ignorant about it). It's not about lazyness, it's about not mundanely repeating yourself – Wader

Answer 2

I have just taken a C# solution and did just this (remove any file that had multiple public classes in them) and broke them out to individual files and this has made life much easier.

If you have multiple public classes in a file, you have a few issues:

1. What do you name the file? One of the public classes? Another name? People have enough issues around poor solution code organization and file naming conventions to have one extra issue.

2. Also, when you are browsing the file / project explorer, it's good that things aren't hidden. For example, you see one file and drill down and there are 200 classes all mushed together. If you have one file per class, you can organize your tests better and get a feel for the structure and complexity of a solution.

I think Java got this right.

Lambda

Yeah, it makes total sense to me. Not just because I'm a Java programmer, but because it makes the naming scheme just sort of fall into place on its own. – Gormandize

In C# code 99% of situations where I have several public classes in one file is: one public full-lown class and a few interfaces, enums or delegates this class uses. – Steatopygia

On the other hand, I still think decision should be left to the developer, not enforced. – Steatopygia

maybe, but flexibility is not always the best thing. More and more we are seeing the benefits of solutions built on convention over configuration. – Lambda

Answer 3

From Thinking in Java

:

There can be only one public class per compilation unit (file).
The idea is that each compilation unit has a single public interface represented by that public class. It can have as many supporting “friendly” classes as you want. If you have more than one public class inside a compilation unit, the compiler will give you an error message.

---

From the specification (7.2.6)

When packages are stored in a file system (?7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:

• The type is referred to by code in other compilation units of the package in which the type is declared.
• The type is declared public (and therefore is potentially accessible from code in other packages).
• This restriction implies that there must be at most one such type per compilation unit.
• This restriction makes it easy for a compiler for the Java programming language or an implementation of the Java virtual machine to find a named class within a package; for example, the source code for a public type wet.sprocket.Toad would be found in a file Toad.java in the directory wet/sprocket, and the corresponding object code would be found in the file Toad.class in the same directory.

In short: it may be about finding classes without having to load everything on your classpath.

Edit: "may choose" seems like it leaves the possibility to not follow that restriction, and the meaning of "may" is probable the one described in RFC 2119 (i.e. "optional")
In practice though, this is enforced in so many platform and relied upon by so many tools and IDE that I do not see any "host system" choosing to not enforce that restriction.

---

From "Once upon an Oak ..."

It's pretty obvious - like most things are once you know the design reasons - the compiler would have to make an additional pass through all the compilation units (.java files) to figure out what classes were where, and that would make the compilation even slower.

(Note:

the Oak Language Specification for Oak version 0.2 (postcript document): Oak was the original name of what is now commonly known as Java, and this manual is the oldest manual available for Oak (i.e. Java).
For more history on the origins of Java, please have a look at the Green Project and Java(TM) Technology: An Early History
)

Dispersoid

@VonC: Just to be clear, the text that you quoted from the JLS says that a Java platform may forbid multiple classes per source file. It does not say that it must forbid this. (But you shouldn't do this anyway. If you do, your source code won't compile on some platforms; e.g. in typical IDEs.) – Roethke

'May' may have a different meaning in standards documents than in natural speech... – Mooned

@Stephen, Eric: I just added a small section about the meaning of "may" in specifications. It is true it does not say "must", but still... it seems enforces in too many place already. – Dispersoid

Answer 4

It's just to avoid confusion in the sense that Java was created with simplicity in mind from the perspective of the developer. Your "primary" classes are your public classes and they are easy to find (by a human) if they are in a file with the same name and in a directory specified by the class's package.

You must recall that the Java language was developed in the mid-90s, in the days before IDEs made code navigation and searching a breeze.

Dumond

IDEs have been around since the mid 80s (at least) - ever heard of Turbo Pascal? – Mardis

IF the decision to put each public class in a file was JUST for 'easy to find (by a human)..' a newbie like me can say it wasn't a correct decision – Gadabout

Yes - I know; I started using Smalltalk which has been around for a long time and comes with an IDE by design. But Java was created to be more like C/C++ (for better or worse) and I think my point still stands – Dumond

@oxbow Neither C nor C++ has any mapping between file name and class. And IDEs have been available for both for years - I remember using the DeSmet C IDE in the mid 80s – Mardis

Java? Simplicity in mind for the developer? It doesn't look like that to me. – Basie

@Neil - sorry, I didn't put that very well. I wasn't implying that C or C++ had one class/file. I was implying that they didn't have extensive IDEs at that time. I may be wrong about this but the early Java IDEs (JBuilder for example) had appalling code navigation. I for one am glad that they chose a single public class per file. – Dumond

@Dumond Look at #1319212. Looks like it was for easier to find for compiler and not for human – Gadabout

@Sandbox. Very interesting, though I'm not sure about your implication that decisions made solely for the benefit of humans are not made on a good basis. – Dumond

@Dumond Didn't really intend to imply that. Just that I couldn't digest that the decision was made so as to make it easier to find files for humans. – Gadabout

Answer 5

It is technically legal to have multiple Java top level classes in one file. However this is considered to be bad practice (in most cases), and some Java tools may not work if you do this.

The JLS says this:

When packages are stored in a file system (§7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:

• The type is referred to by code in other compilation units of the package in which the type is declared.
• The type is declared public (and therefore is potentially accessible from code in other packages).

Note the use of may in the JLS text. This says that a compiler may reject this as invalid, or it may not. That is not a good situation if you are trying to build your Java code to be portable at the source code level. Thus, even if multiple classes in one source file works on your development platform, it is bad practice to do this.

My understanding is that this "permission to reject" is a design decision that is intended in part to make it easier to implement Java on a wider range of platforms. If (conversely) the JLS required all compilers to support source files containing multiple classes, there would be conceptual issues implementing Java on a platform which wasn't file-system based.

In practice, seasoned Java developers don't miss being able to do this at all. Modularization and information hiding are better done using an appropriate combination of packages, class access modifiers and inner or nested classes.

Roethke

The JLS says nothing (normative) about the subject. – Dare

Answer 6

If a class is only used by one other class, make it a private inner class. This way you have your multiple classes in a file.

If a class is used by multiple other classes, which of these classes would you put into the same file? All three? You would end up having all your classes in a single file...

Mead

Answer 7

That's just how the language designers decided to do it. I think the main reason was to optimize the compiler pass-throughs - the compiler does not have to guess or parse through files to locate the public classes. I think it's actually a good thing, it makes the code files much easier to find, and forces you to stay away from putting too much into one file. I also like how Java forces you to put your code files in the same directory structure as the package - that makes it easy to locate any code file.

Fourierism

Answer 8

Why is java not removing this restriction now in the age of IDEs? This will not break any existing code (or will it?).

Now all code is uniform. When you see a source file you know what to expect. it is same for every project. If java were to remove this convention you have to relearn code structure for every project you work on, where as now you learn it once and apply it everywhere. We should not be trusting IDE's for everything.

Mercenary

Answer 9

Not really an answer to the question but a data point none the less.

I grepped the headers of my personal C++ utilty library (you can get it yourself from here) and almost all of the header files that actually do declare classes (some just declare free functions) declare more than one class. I like to think of myself as a pretty good C++ designer (though the library is a bit of a bodge in places - I'm its only user), so I suggest that for C++ at least, multiple classes in the same file are normal and even good practice.

Mardis

Answer 10

It allows for simpler heuristics for going from Foobar.class to Foobar.java.

If Foobar could be in any Java file you have a mapping problem, which may eventually mean you have to do a full scan of all java files to locate the definition of the class.

Personally I have found this to be one of the strange rules that combined result in that Java applications can grow very large and still be sturdy.

Chalybite

Answer 11

Well, actually it is an optional restriction according to Java Language Specification (Section 7.6, Page No. 209) but followed by Oracle Java compiler as a mandatory restriction. According to Java Language Specification,

When packages are stored in a file system (§7.2.1), the host system may choose to enforce the restriction that it is a compile-time error if a type is not found in a file under a name composed of the type name plus an extension (such as .java or .jav) if either of the following is true:

• The type is referred to by code in other compilation units of the package in which the type is declared.
• The type is declared public (and therefore is potentially accessible from code in other packages).

This restriction implies that there must be at most one such type per compilation unit. This restriction makes it easy for a Java compiler to find a named class within a package.

In practice, many programmers choose to put each class or interface type in its own compilation unit, whether or not it is public or is referred to by code in other compilation units.

For example, the source code for a public type wet.sprocket.Toad would be found in a file Toad.java in the directory wet/sprocket , and the corresponding object code would be found in the file Toad.class in the same directory.

To get more clear picture let's imagine there are two public classes public class A and public class B in a same source file and A class have reference to the not yet compiled class B. And we are compiling (compiling-linking-loading) class A now while linking to class B compiler will be forced to examine each *.java files within the current package because class B don’t have it’s specific B.java file. So In above case, it is a little bit time consuming for the compiler to find which class lies under which source file and in which class the main method lies. So the reason behind keeping one public class per source file is to actually make compilation process faster because it enables a more efficient lookup of the source and compiled files during linking (import statements). The idea is if you know the name of a class, you know where it should be found for each classpath entry and no indexing will be required.

And also as soon as we execute our application JVM by default looks for the public class (since no restrictions and can be accessible from anywhere) and also looks for public static void main(String args[]) in that public class. Public class acts as the initial class from where the JVM instance for the Java application (program) is begun. So when we provide more than one public class in a program the compiler itself stops you by throwing an error. This is because later we can’t confuse the JVM as to which class to be its initial class because only one public class with the public static void main(String args[]) is the initial class for JVM.

You can read more on Why Single Java Source File Can Not Have More Than One public class

Unguinous