Great code review. Names matter.

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

Functions

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

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

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.)

Any questions are welcome!

iOS developer, TeamLead. Love engineering, guitars, martial arts and learning