Clean Code: A Handbook of Agile Software Craftsmanship’s summary Chapter 2: Meaningful Names

The link to chapter 1’s summary is here.

When I was working as an associate data scientist, I had an opportunity to work with a newly appointed Data governance manager in a newly formed Data department. It was then I realized the power of meaningful names and their standard definition across the company. If two people are talking about one topic and do not refer to the same definition of that term, conflict is bound to happen! Real life scenario could be definition of love.It can be defined differently by different people, make sure you both agree to the same definition of love before dating 😉 and obviously behaviors/actions have to comply to the original defined and agreed upon term. And of course amendments are possible!

Now, let me take your attention to Uncle Bob’s simple rules for creating good names:

Use Intention-Revealing Names:

The name of a variable, function, or class, should provide answer to questions such as why it exists , what it does and how it is used ? it should remove the need of a comment.

for example:

int s[]; can be renamed as int Scores[];

The reader(of course a coder)of your code should not have a difficult time understanding what is going on.

Avoid Disinformation:

“Spelling similar concepts similarly is information. Using inconsistent spellings is disinformation.”

Remove the false clues that conceals the meaning of code. for example using lowercase L and uppercase o as variable names which may confuse one because lowercase L (l) looks like one(1) and uppercase o(O) looks like zero(0).

Make Meaningful Distinctions:

Do not use noise words because they are redundant. For example, if you have used the variable ‘count’ in your program than do not use another variable ‘theCount’. other examples uncle Bob provides is that ‘variable’ should not appear in a variable name and ‘table’ should not appear in table name.

Naming 3 different functions such as getActiveUser() , getActiveUsers() and getActiveUserInfo() would create confusion to a programmer on which function to call if she is trying to count the total number of active users.

‘amountOfMoney’ is indistinguishable from ‘money’.

Hence, Uncle Bob recommends to choose names in a way that the reader knows what the difference has to offer!

Use Pronounceable Names:

int ndinhrs; ndinhrs is not pronounceable hence it should be converted to int numberOfDaysInHours which is pronounceable;

I was once interviewed by a principal software engineer who literally named a variable with five letters with each letter representing a word. I kindly had to ask him what it means and he blurted five technical words with proud voice as if he was a genius for making an invention of five letter variable. It was my final round interview and I had aced interview with 2 other interviewers but failed with him. I am assuming that probably it has to do with me constantly asking him for further clarifications. I did not know till this date if mistake was mine, but after reading uncle Bob’s rule, I figured my questions were valid! It feels good to work with people who possess growth mindset and are transparent and open to communication.

Use Searchable Names:

Examples are const int EMPLOYEES_IN_A_COMPANY = 24;

If one wants to look for the number of employees in a company the above variable naming is more searchable than using the number 24 which might appear multiple times and could represent different thing.

Avoid Encodings:

Encoded names introduce the possibility of mistyping and are seldom pronounceable.

Don’t use Hungarian Notation and Member Prefixes

Interfaces and Implementation:

Do not use any identifier variable after the name of an interface such as adding I in front of an Interface name. You can however add an identifier variable for the implementation of an interface by adding Imp or Impl at the end of the class that implements the interface.

Avoid Mental Mapping:

Professional programmers know that clarity is the king. Hence, they should avoid using a single letter for loop counter. Readers should not have to mentally map your choice of names to something that readers understand.

Class Names should be Nouns

Method Names should be verbs

Don’t be cute:

“Say what you mean, Mean what you say.” do not use the term whack() to mean kill().

Pick One Word per Concept:

It is confusing to have different words for similar methods even if they are in different classes. For example: you can pick get() instead of using 3 different variations of same concept such as fetch(), retrieve() and get(). Similarly, one word could be picked out of manager, driver, or controller in the codebase.A consistent lexicon can add to a greater overall productivity.

Don’t Pun:

Our goal is to write our code as simple as possible. Do not use the same word to represent two different context. When semantics are different, use a different word to preserve the semantics.

Learn to separate solution and problem domain concepts and name variables likewise

Add Meaningful Context:

If you want to represent an address. You can name variables such as addrCountry, addrState, addrCity, and addrZipCode. Split the longer functions into pieces to allow the improvement in the context thereby making algorithm much cleaner.

Don’t Add Gratuitous Context:

If Uncle Bob would want to differentiate among MAC addresses, port addresses, and Web addresses, he would name them MAC, portAddress and URI respectively instead of adding address context to each unnecessarily.

Final words:

Uncle Bob emphasizes the value of good descriptive skills and a shared cultural background to come up with good names. He believes that it is a teaching issue rather than a technical, business or management if someone fails to acquire good descriptive skills .

He advises to follow the rules he devised and see the change in readability. He asks to refactor the code according to his rules using refactoring tools and enjoy the short term as well as long term pay offs.

Summary for chapter 3: Functions can be found here.