- Less time spent on reading and glancing at code.
- Reduced need for understanding the code base as a whole to understand any given function / scope.
- More precise and concise information presented upon first glance.
- Easier for new developers, and developers as a whole, to understand the code base.
No Spelling Mistakes
- Searching through the code base is more difficult: if you are searching for "networkInterceptor" and one of the variables or functions has "Intercepter" in its name, the thing you're looking for might not appear in your search results.
- Future refactoring may be more costly: a future refactor initiative may require that the spelling mistake be resolved to make the system more self-consistent. If a spelling mistake has propagated over time, it will put more work on the developers who are tasked with refactoring the system and correcting this mistake.
- Developers may be less motivated to write clean code: in extreme cases where a codebase is littered with misspelled names, or when only a few culprits are referenced from many places, the developer's motivation may go down. This may seem far fetched upon first glance, but it makes more sense when considering this in the context of an analogy: if a person is walking down a hallway in pristine condition with polished floors and sparkling glass, they will almost feel obligated to keep it that way as they walk through. If, however, that hallway is dirty with trash on the floor and dirty walls, they might be more inclined to litter, since it apparently won't make any difference to the overall condition.
Spelling mistakes, as well as mistakes in general, are impossible to avoid entirely, but good code review policies and an overall attention to detail will prevent this type of issue from propogating.
Avoid Negated Names
A "negated name" is a name with not, isn't, or something similar within the name itself. This rule applies primarily to variables which hold boolean values and functions which return them. In the case of booleans, any negated name implies a negated value. For example: the name isNotValid will return false when the subject in question is valid. This will force the developer to always need to remember to flip the true/false in their mind when dealing with the variable/function and actually do so in each case. A single missed flip can lead to a bug or defect. An even worse situation: the name is negated but the actual value is not; a situation which certainly must be avoided.
Use Consistent Casing
Common casings include camel case, pascal case, and snake case. Different languages and projects have their own standards, but it is important to keep the standard consistent throughout the repository / code base. Sudden shifts in the naming convention will slow down any developer scanning through or reading that part of the codebase. If there is a shift in convention, there should be a very good reason for doing so.
Use Specific Names for Specific Things
A common mistake when naming variables and functions is to use a generic name for something that is specific in nature. For example, if we are in a system where users can change their settings, we may need to check if a user has a certain setting turned on take some action if they do. If the user has a setting to enable dark theme for their account: a good variable name might be isDarkThemeEnabled. A bad variable name would be isSettingOn. The former outlines the specific setting in question whereas the latter does not. It will not be immediately clear which setting the variable is referencing (it could possibly represent whether user settings as a whole are enabled). This problem will be compounded if the variable name is passed through multiple functions or scopes.
It is important to note that there must still be a balance between conciseness and specificity. In the example above, we might have called the variable isUserDarkThemeSettingOn, but that name has 24 characters, which may be a bit excessive. As long as the name is descriptive enough, the context should take care of the rest, so long as the context itself is not confused.
Avoid Type Encodings in Names
- The information is redundant: in statically typed languages, the type information will be present at the variable's / function's declaration. In dynamically typed languages where static typing is not available or is not used, the name of the variable can still be descriptive enough without needing a type name within the variable name itself.
- It takes longer for the developer to skim through or read the code: if every string variable has "str" or "string" suffixed to its name, the reader will need to filter more of the text on the screen. Each redundant prefix will take more space on the screen without conveying any additional information.
- If the type is changed through a refactor, all references will need to be updated, including consumers: For example, a developer might realize that certain redundant operations are being performed over strings and decide to create a special class for this type of operation. When the type definition is changed from string to this new class, the "str" suffix will no longer make sense and will need to be updated. This means that all references will also need to be updated. If there are any external references, those too will need to be updated, and that process may be a bit tricky.
Some words or abbreviations can be used in a variable name without falling into this condition. For example, calling a variable usersList is declarative without encoding too much type information; a list is a generic concept not tied to any specific type. With this in mind, a certain balance can be struck so the name can still convey something about the nature of the variable / function without encountering the problems listed above.
Considering Queries and Commands
This applies mainly to functions. It should be clear within the function's name whether it is checking the state of something or altering its state. For example, a function called isLoggingEnabled should not do work we would expect a function called sendLog to do. Similarly, a function called readLastReport should not write a new report to the database it's reading from. This is a straightforward rule but one which is sometimes violated.