Many of developers make code review of their peers and colleagues and everybody knows that naming is one of the most important aspects of high quality code.
Let's talk about naming: why it's so important, which names are good and which principles should we follow to create great code.
Why naming is so important
Good names of classes, variables and functions are important because they reflect idea, purpose and reason of their creation. If the code contains elements with unclear names, it has a "code smell" and this is an indicator of overall poor code quality.
If all principles are followed and elements really reflect their purpose, you may easily identify places to improve in the code or potential architectural changes or enhancements.
Which names are good
Every function, class or variable should reflect it's main purpose of creation in the name. As a rule, class or structure represents an object, function represents an action and variable represents a state of something. Let's take a look into naming principles.
Classes / Structures / Enums / Protocols / Interfaces
Name can be chosen with following template:
[PurposeOfTheUnit][UnitName] or [UnitName].
Example: "Point", "UserDataManager", "DataStorage", "UserProfile" and so on
The template for functions is:
[Action][With which input parameters][Other meaningful addition]. Important: names of the functions should be convenient with returning result.
For example: "calculateDelta(…) -> [Result of calculation]", "updateView()", "refreshPageIfNeeded()"
Missing of [Action] is a bad mistake, because main purpose of any function is to make an action.
Variables should just have good enough description of their purpose in current context (class member or local function variable). Of course, there is a group of variable names that are accepted in the whole SW development industry over the years (i, k, j, id and so on) and may be easily used. Also short names sometimes acceptable if they are in correct context ("sw" as "south-west coordinate" in function with calculates the distance, for example)
Example: "i", "eventCounter", "viewState"
Which names are bad
Following to one of my favourite principle: "use patterns and avoid anti-patterns", we need to talk about bad naming. These are most frequent cases:
- non-meaningful names / not clear names
"event". Not clear is that a kind of any event or state, or some action with the event
- wrong abstraction levels
Names should be chosen according to their abstraction layer. For example, if you have a class called UnitsStorage, it should have functions which deal with "Units", but not "specific types of Units"
- names of function which does not reflect actual function action(s)
calculateDelta(…) which actually does the print inside. I think, this is critical point because correct function name may indicate SRP (single responsibility principle) following.
Which names are inconvenient
Names that do not reflect situation quite well. For example, there is no need to call variable "iteractionNumber" in for-loop, "i" is enough in 99% of cases. And vice-versa: "eC" does not fully reflect the idea of "eventCounter" on class level.
Tips and recommendations
- Follow code style guides of the language you use (swift, java, c#, etc.)
- Prefer clarity over brevity
- Reflect the idea in the name
- Apply ideas from this articles
Any questions are welcome!