This is part of a brief series on Good Habits For Java Programmers.
Be conventional
Java does not require that you declare your fields at the top of the class and your methods below that. But that's what we do conventionally. Java does not require that constructors are placed above other methods, but that's what we do. I think both of those habits promote readability on their own -- that it's generally easier to comprehend a class that way. But I'm not sure because that way of presenting a class is extremely conventional -- it's what everyone in the industry does. So I can't tell if these placements inherently make a class more readable, or they make a class more readable because I'm used to seeing a class presented that way and so can find my way around the class more easily when people obey the convention. Convention and patterns are very powerful tools for promoting understanding.
You should be conventional, too, and follow those rules.
The rest of what I'm going to say is definitely not universally practiced convention. In fact, for much of my career, I didn't follow these rules. When I joined Block (nee Square), I was taught these rules, and I found them extremely helpful. So I'm passing them on to you.
Put public things before private things
I know, I know, we instructors are such nuisances when it comes to access modifiers, always telling you when you left something public that should be private. We harp on it so. It's annoying. But it is important.
If you follow the rules in this post, you probably don't have public member fields, but there can be reasons to make exceptions as you progress. Put all the public fields above the private fields.
You almost certainly will have public and private methods though. Same rule: put the public ones above the private ones.
Why? It goes back to why we even make the distinction between public and private access modifiers. Our publicly modified bits of code are available to any class to access. They represent the public face of your class: it's what is advertised to the rest of your classes what they can do with your class. So programmers trying to use your class will want to know what they can do about it, and putting that information at the top of the class is helpful.
On the flip side, the programmers who use your class don't really care how it's implemented, so they don't care to or need to read or pay attention to your private helper methods. Those are there for your class to do as it advertises it does, but people who use your class don't care and shouldn't care about those details.
This may all be too abstract and you may not have had enough experience working on a shared project or a large project to appreciate this. In that case, I'm sorry to say you should just treat this as advice that some day will make more sense to you if you continue to program. At the least, it's a rule, and it provides a convention you can be consistent with, and that has value.
If possible, calling methods go on top of called methods
If you have a method private Date getDate() and it uses a helper method private boolean isValidDate(Date date), all things being equal, put getDate above isValidDate. That way, when you or anyone else is reading your code, they can follow the bigger picture before diving into the details. They will read that getDate relies on isValidDate and set that aside. Later, they can figure out what isValidDate does.
Here's another way to think of it. In English, we read from the top of the page down. And in general, when reading, we expect to encounter the more important things before the less important things. So we expect meatier, more algorithmically relevant methods to come first, and their helpers to come later.
Sometimes you can't always obey this: you have methods crisscrossing in how they all call each other. That's okay. Just do your best. Exercise judgment over which should come before the other, focusing on what makes it easier for someone reading your class to figure out how it works.
Violate these rules if it makes sense
Readability, discoverability, and maintainability are the real goals here. If it seems to you that they are better met by a different ordering, go for it. As long as you're motivated by making your class easier to use or to understand or to maintain, you're focusing on the right things.
Where does main go?
What about public static void main(String args[])? If that's in your class, where should it go?
This is sort of a trick question. It probably shouldn't be in your class at all. But if it is there, I recommend it be either the first thing we see, above your fields, or just after your fields. I do have one friend who says he would be surprised to see it anywhere except at the bottom of a class, though. Wherever it gets put, it's incredibly important that it can be spotted easily and quickly, and not buried away in the middle of your class.
But as I said, you know what makes it even easier to spot and less hard to find a place for in your class? Not having it in your class to begin with. Okay, it has to be in some class. How about in a class named Main, dedicated to housing main?
Top comments (0)