I am putting my experience about importance of correct naming. I feel correct naming is the key in deciding object’s responsibilities (methods, variables).
Developers frequently hear that “not to spend too much time on naming”. This holds true. If you can’t get a specific name in short time (10mins?), be pragmatic and move on. Later you can revisit, if you find better.
But that doesn’t mean we shouldn’t pay attention for naming something accurately. I am talking about naming variables, classes, functions, interfaces, database fields, etc. In general, object naming.
Issues with incorrect naming
Here are some of the problems I see when naming is not done correctly:
- While doing code reviews, I have to ask developer the purpose of a particular badly named object.
- Help code reviewer to focus on more important issues than arguing over syntax and naming.
- Lot of brain power wasted to read and understand source code.
- Naming is not critical from a code perspective nor from a computer’s perspective. But from a developer habit perspective. This is because if we don’t name it accurately, our brain doesn’t get proper instructions from the class names and we end up putting things in that class that shouldn’t belong there. We end up giving a responsibility to an object when that responsibility belongs to some other object.
- Naming something as data or details. When you see variables like SomethingData or SomethingDetails, it indicates that developer didn’t find good specific name and so he ended up with details. This is what I have seen, not necessarily true in every case. Let’s say we have OrderDetails. Looking at the object name, can anyone infer what kind of details are present on this object? Same goes with RequestData. When name is not specific, other developers tend to abuse that and put whatever details they want to. I have seen such objects end up growing very large like god objects.
- Calling somethingManager usually means the class is doing more than one thing. I am not talking about the suffix given to MVC controllers in few frameworks. These are library classes which usually end up doing more than one thing thus breaking Single Responsibility Principle. Here changing name doesn’t solve the problem, but its an indication of incorrect naming and not breaking responsibilities properly.
How to name objects
- According to Uncle Bob, (Author of Clean Code), we should name a variable with the same care we do in naming a first-born child. After all, we are going to need to be able to call it, know what it’s for, and not confuse it with any other variables in our classes.
- Names should be “intention-revealing” names.
- Names should reveal:
- Why does it exist?
- What does it do?
- How is it used?
- Classes are acting as an actor, they do something. So it makes sense to have nouns for naming such classes.
- Interfaces, method names are actions, behaviors. So it makes sense to have verb for naming these.
- Method – fetchSomething gives me indication that its going to fetch something from different layer like database or external request. I would avoid naming getSomething() for such methods. Use one word per concept and don’t use same word for 2 concepts.
- Accessor methods or getter functions should be prefixed with get*. E.g.: getOrder(), getCustomer(). A getter function shouldn’t update or mutate anything. No side effects.
- Setter functions should be prefixed with set*. E.g.: setOrder(), setCustomer(). These function’s shouldn’t return anything (exception of fluent functions for method chaining).
- Give names that are used in business domain. Domain Driver Design encourages to give names in a way that business people can read the class and understand what’s going on.
- Obey company naming standards and write method names consistently in application
- Most important: We are writing code for humans and not for computers. Give names that other humans would understand.
- If named correctly, you don’t need a comment to explain. When you feel the need to write a comment for a function or variable, its an indication that you have not named it correctly. Self documented code is a beauty!
- Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- i.e., designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary “throw-away” variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters.
This is an active post. I keep on updating it as I find new patterns while doing code reviews.
