Is naming identifiers like classes, methods and variables important in developing clean code? It is.

Below is a set of simple rules that you can use as a quick reference to name your identifiers correctly:

1. Use intention revealing names that can explicitly tell why it exists, what it does and how it is used, so that others can easily understand the code. E.g. int elapsedTimeInDays instead of int d.

2. Avoid names or usages that may give false clues or create confusion in the minds of readers. For instance, an abbreviation that may mean two different things when expanded, long and similar names with only very little difference, etc. should be avoided. A variable named l (small el) will be against this note and even the previous note. This can be confused with 1 (one) in use cases such as in ‘int someInt = l;’

3. Don’t alter variable names simply to satisfy the compiler or interpreter by misspelling it or adding numbers or using words that mean the same; instead make a meaningful distinction. For instance, var and vaar, var1 and var2, or even ProductInfo and ProductData should not be used together just for satisfying the compiler or interpreter.

4. Use names that can be pronounced easily so that you can discuss them with others without much trouble. For instance, CustomerInfo is a far better choice than CstInf.

5. Use searchable names matching the context instead of using constants directly so that we can search for the occurrence easier. For instance, a constant variable DAYS_OF_WEEK having a value of 7 would be better than directly assigning 7.

6. Avoid encoding type or scope information into names, as it adds an extra burden, and new developers would have to learn the encoding to understand better. For instance you may be tempted to add int to all int variables. Adding type to name is less significant in strongly typed languages like Java as it remembers the type of every variable.

7. Sometimes it might be acceptable to use encoding to distinguish interfaces and implementations. However, instead of encoding the interface with some prefix, it is better to encode the implementation. E.g. ObjectFactory and ObjectFactoryImpl.

8. Use solution domain or problem domain names instead of random names or single letter names where reader will have to mentally translate the name into something meaningful in the context. Solution domain names like computer science terms, algorithms, patterns etc. should be preferred over domain names, as your code would be read by programmers. E.g. AccountVisitor when using the visitor pattern will be easier to understand for programmers.

9. Class names should have noun or noun phrase names like Customer, Account etc. and should not use words such as Manager, Processor etc.

10. Method names should have verb or verb phrase names like deletePage, save etc.

11. Instead of overloading constructors, use static factory methods with names that describe the arguments, and can also consider enforcing it by making all constructors private.

12. Colloquialisms or slang should not become part of your variable names as it will be understandable to only few subsets of people.

13. Equivalent methods in different classes of the same code base should be given same name; otherwise if we name 3 similar methods as fetch, retrieve and get, readers may get confused and would have to remember which one belongs to which class. Select one word for an abstract concept instead of three different words as in this case. However, you should not overuse this principle and should try to avoid using the same name for different purposes.

14. You should add meaningful contexts to variables, either by enclosing them in a well names class, method or namespace; or if that does not happen, then prefix the context as a last resort. For instance, if a state variable comes along with name, city etc. in a Person class, its context is well understood, but if a state variable comes unattached you may have to call it addrState instead as state may also mean something else in some other context like a state machine implementation. However, should also make sure that you add no more context to the names than necessary. For instance, it would be a bad idea to prefix every class belonging to an application with a common prefix just because you can find them all together.

15. Shorter names are generally better than longer ones as long as their meaning and context are clear.

References

This note is based on the book “Clean Code” by “Robert C. Martin”. The chapter ‘Meaningful Names’ explains all these rules in detail along with examples.