What Is Clean Code 🔗 Naming Conventions — Part 2
In Part 1, I summarized what clean code means in common sense and started to talk about Naming Conventions. I will continue to mention this in this article.
8- Avoid Mental Mapping
Mental mapping happens most often when authors of code obscures their intents by either using single-letter variables or when authors can’t make a choice between problem domain terms and solution domain terms. There are few exceptions with single-letter naming. If scope of code is very small and no other names can conflict with it, loop counters can be named as i, j, k because they are familiar to programmers.
One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king.
9- Class Names​
Classes and objects should have noun or noun phrase names and should obey Single Responsibility Principle. It is always better to avoid noise words — Manager, Data, Info, etc. This blog is also nice to understand class naming in a better way and why Manager naming is not a good idea.
10- Method Names​
Methods should have verb or verb phrase names and it is better to name accessors, mutators with javabean standart. Use static factory methods for overloaded constructors by making corresponding constructors private to enforce developers’ usage. For instance Conversion.FromDouble(5.9) and Conversion.FromInt(6) could be nice naming if we had two different constructor for one class.
11- Don’t Be Cute​
Using slang language or jokes in code just to show we are clever or just to have fun can hide the intention of author or even mislead readers and thus we should avoid.
Choose clarity over entertainment value.
12- Pick One Word per Concept​
Avoiding the use of similar names for equivalent methods in codebase can make the code cleaner. For instance having fetch, retrieve, get for similar concepts or having controller, manager in the same codebase can be confusing for readers.
13- Don’t Pun​
Sometimes when we try to follow the “one word per concept” rule, we might me tempted to use same names even though they don’t have really same semantics or concept.
Let’s say we have many classes where add will create a new value by adding or concatenating two existing values. Now let’s say we are writing a new class that has a method that puts its single parameter into a collection. Should we call this method add? It might seem consistent because we have so many other add methods, but in this case, the semantics are different, so we should use a name like insert or append instead. To call the new method add would be a pun.
14- Use Solution Domain Names​
Use computer science (CS) terms, algorithm names, pattern names, math terms, and so forth because readers and writers will most likely be developers and they won’t be familiar with problem domain names.
15- Use Problem Domain Names​
If there is really no “programmer-eese” for what we’re doing, and the code has intensive problem domain logic, it is better to use problem domain names since developers can ask a domain experts what it means.
16- Add Meaningful Context​
Names themselves mostly doesn’t give a meaning to us, thus contexts(can be well-named classes, functions or even prefixing the name) in names help us to understand better.
Imagine that you have variables named firstName, lastName, street, houseNumber, city, state, and zipcode. Taken together it’s pretty clear that they form an address. But what if you just saw the state variable being used alone in a method? Would you automatically infer that it was part of an address?
You can add context by using prefixes: addrFirstName, addrLastName, addrState, and so on. At least readers will understand that these variables are part of a larger structure. Of course, a better solution is to create a class named Address. Then, even the compiler knows that the variables belong to a bigger concept.
17- Don’t Add Gratuitous Context​
As long as names are clear, shorter ones are most likely better than longer ones. So adding module or application name prefixes to every class or function, can be consider as encoding, would be impediment and gratuitous context for developers and even can cause to disinformation. Gratuitous contexts make it harder to search as well.
That’s all folks! And even though I summarized general ideas for how naming should be, each sections deserve their own articles. Any feedback for improvements, problems will be much appreciated by me. :) Hope to see you next time.
