Meaningful Names - A Dimension of writing Clean Code.
Reaching the state of functional simplicity is not easy as it sounds. Writing clean code is an art and it requires practice, a lot of it.
And by the way writing clean code is not a linear, it requires cleanliness in multiple dimensions of writing code which I call them as Clean Code Dimensions.
Of which “Naming” takes the pride of being most important.
Yes. It all starts with Naming. Phil Johnson, Writer/Editor at IT WORLD, said “Naming Things is the hardest of things that programmers have to do”. If you’re a team player then its the most important aspect of code understandability that you must consider. But each of your teammate might do naming based on their taste, intuition or any driving factor. That is more worse. The solution is to have a ‘Naming Convention’.
Having a fully agreed truce on ‘Naming convention’ reduces the effort needed to read and understand source code, which eventually give us following benefits,
- Improved Communication — “The best code communicates itself” . Any member of a development will be able to read and understand the code of another member through code.
- Improved Code integration — Distinct teams that rely on the code built by other teams won’t have problem understanding properly named interface and its entities.
- Improved Consistency — Helps formalize expectations and promote consistency within a development team.
- Improved clarity — Provides better understanding in case of code reuse after a long interval of time. Enhances clarity in cases of potential ambiguity.
In order to agree upon a Naming Convention, we require knowledge of how names must be designed. Following are my takeaways from various blogs and books which teaches best about naming which will help you acquire that knowledge.
Use intention revealing names
The names of variable, functions, class etc. should tell you why it is exists, what it does and how it is used. For instance, let’s consider ‘variable names’. For a variable name which holds a value of a measurement, we should choose a name that specifies (i) what is being measured and (ii) the unit of that measurement.
For example,
int d; // This variable name reveals nothing
int fileAgeInDays; // This reveals what is being measured and unit of measurementMake meaningful distinctions
Distinguish names in such a way that reader knows what the differences offer.
For example,
moneyAmount is indistinguishable from money,
moneyInRupees is clearly distinguishable from moneyInDollars.
Use pronounceable names and searchable names
If you can’t pronounce a name it requires an effort of look-up to understand. When a name is pronounceable mostly it is searchable and searchable names is a must to enhance find operations in refactoring. Single letter names must be used only as local variables.
For example,
private Date timeStamp;is better than
private Date tmStmp;Function names should be verbs
Methods should have verb or verb phrase names like postPayment, deletePage, or save. Accessors, mutators, and predicates should be named for their value and prefixed with get, set, and is according to the javabean standard.
For example,
String name = employee.getName();
customer.setName("mike");
if (paycheck.isPosted())...When constructors are overloaded, use static factory methods with names that describe the arguments.
For example,
Complex fulcrumPoint = Complex.fromRealNumber(23.0);is generally better than
Complex fulcrumPoint = new Complex(23.0);Consider enforcing their use by making the corresponding constructors private.
Pick one word per concept
Pick one word for one abstract concept and stick with it.
For instance, it’s confusing to have fetch, retrieve, and get as equivalent methods of different classes.
Don’t add gratuitous context
In an imaginary application called “Foo Solution” it is a bad idea to prefix every class with FS. Frankly, you are working against your tools. You type ‘F’ and press the completion key and are bombarded with a mile-long list of every class in the system.
Avoid encodings
In modern languages, we have much richer type systems, and the compilers remember and enforce the types. What’s more, there is a trend toward smaller classes and shorter functions so that people can usually see the point of declaration of each variable they’re using.
Java programmers don’t need type encoding. Objects are strongly typed, and editing environments have advanced such that they detect a type error long before you can run a compile!
They make it harder to change the name or type of a variable, function, or class. They make it harder to read the code. And they create the possibility that the encoding system will mislead the reader.
PhoneNumber phoneString;
// name not changed when type changed!Should we avoid prefixes for member and static variables — mVariable,sVariable ??
Robert.C .Martin, in his book ‘Clean Code’, says, “Your classes and functions should be small enough that you don’t need them. And you should be using an editing environment that highlights or colorizes members to make them distinct.”
Jake Wharton calls this practice a “Plague that has infected Android apps and libraries”.
I find nothing infectious or potential bad impact that these prefixes will have in my code. This convention of using m-prefix for member variables and s-prefix for static variables have only helped me to be extra conscious about its usage. In combination with modern IDE, they help me in learning a list of member and static variables available in a class (for example, By typing ‘m’, my IDE will reward me list of mVariables i.e. member variables). So I consider using prefixes for identifying member and static variables good. Even though modern IDEs like IntelliJ IDEA, Eclipse support prefixes for member variables, there are many contexts where prefixes for member variable may hinder your productivity by incurring unnecessary extra work if you’re using mapping libraries for JSON. For new languages like Kotlin getters, setters and constructors are auto-generated by system based on member variable names. So I, leave this to the your choice to decide upon based on your development context.
Conclusion
Naming conventions are always gonna help you, especially when you’re a team. No ones is good at naming especially when you’re hurrying up on to meet deadline. When you have naming convention in place, you won’t have to worry about naming. Hence you produce clean code which will improve your teams communication, your projects’ maintainability and your codebase quality. So, set up your naming convention soon if still don’t have one in place and produce clean code. Happy Coding !
References:
