Java – How to name methods, classes and variables
Names matter a lot in programming.
Even with small functions, if you have cryptic names you won’t be able to understand anything from the code you are reading.
Names are the main tool we have to express intent.
Method names tell you what a method does.
Variable names tell you what that variable contains.
What parts of speech should you use?
Well, classes are nouns: Price, CurrentTrade
Don’t be afraid to use technical words like Service, Component, Repository, Interface, Abstract.
For example UserService, or UserComponent, UserRepository.
They look spammy but in my experience they save time.
This is a bit of a controversial subject.
I actually tried writing code for a while without these helper words and I often found myself lost.
I am in a class called User.
OK, this must be a domain class?
Oh no, it’s the service!
Well why not put service in its name then, instead of making me scroll up and try to figure out what class I’m in?
Helper and Manager must be given a lot of thought and only be used as a last measure in distinguishing this class.
Still, I prefer UserManager to User.
Plain User makes me think it’s a domain object.
UserManager at least tells me it’s not a model.
Variables should be a noun: price, currentTrade.
Verbs would sound silly for variables.
Think of a variable called StartTrading.
What would it contain?
At most a boolean. We will talk about boolean in a moment.
Or maybe it has a function inside it?
It’s weird to think of it as being a float for instance.
It’s like something is missing from its name, if it’s a float.
You want to imagine it’s correct name as being something like: StartTradingThreshhold.
That I understand.
Booleans are are predicates: isScheduled, isRunning
They feel natural in if statements like:
If process.isScheduled do something.
If process.isRunning do something else.
Methods should start with a verb: getStrategyResult, createStrategyResult
Methods that return a boolean, should be a predicate, just like booleans: isScheduled(), isRunning())
Your getters should start with get, don’t make them nouns.
That is a horrible habit.
It looks confusing.
Confusing is the opposite of what we are trying to do when writing code.
Enums should be adjectives.
What about the size of the names?
How big or small should a variable name be?
I’ve had this discussion many times, especially since I like very descriptive variable names.
Uncle Bob in his clean code series talks about something called the scope rule for variable sizes, which makes a lot of sense to me.
If a variable has a small scope it should have a small name.
As long as I can see it’s declaration two rows above I kind of understand what it does.
If a variable has a big scope it should have a big name.
Obviously, this variable is not easy to track, so it should describe itself very well.
The opposite is true for functions and classes:
the bigger the scope, the smaller the name
the smaller the scope, the bigger the name
The idea behind this is that you don’t want to have public functions used everywhere with huge names.
It gets confusing and it’s spammy.
You want often used public functions with small names.
Also, for small scope private methods, you want a big descriptive name.
For example extractFileAndOutputContents.
Private methods are only used in their class, and usually only once.
This means they have a small scope.
So they should describe exactly what they are doing.
It’s ok if they have big names.
You won’t see their name often and you will know exactly what they do.
What not to do when naming things:
Small names.
I often see programmers thinking that if they use very small variable names like tr or dd they will make the code easier to read, because there is less of it.
That couldn’t be further from the truth.
It’s very hard to express intent using a variable like tr or a function name like dd.
Even if it fallows the scope rule i would still promote it to one word.
Names that are not real words.
They are not small but only the programmer that wrote them knows what they mean.
Methods that are nouns.
There’s some sort of need for some programmers to break the rules.
They express it using nouns for their methods.
Don’t do that.
User is not a method name.
DeleteUser is.
This is true for setters and getters also.
The only place where I accepted this was for setters in a builder.
This seems to have become some sort of standard, and it’s too much of a bother to change it in Lombok.
Naming is the best tool we have to express what we do.
It is almost the only way to show our intent.
When you name things, think of the person that comes after you and maintains your code.
Ask yourself:
“How should I name this variable to help the person reading my code understand what it contains”.
“How should I name this function to make him or her understand what this function does”.
Through names, is how your code talks to the programmers reading it.
Through names is how you talk to the programmers reading your code.
Names are clues and signposts in your code.
They guide programmers and help them arrive at their destination.
Don’t be afraid to make names descriptive and meaningful.
This article is part of the “Low Coupling, High Cohesion” episode from my Clean Code course.
You can watch the Clean Code courses here:
– Watch Clean code with Java examples course on Udemy
– Watch Clean code with PHP examples course on Udemy
– Watch this Clean code with Java examples – Basics for free here AND get 2 FREE months of skillshare.com Premium