Naming Conventions From Uncle Bob's Clean Code Philosophy

This article is the result of reading the book "Clean Code" by Robert C Martin. All the recommendations made here are suggested by Robert C Marin. This article covers the abstract of naming conventions suggested by Clean Code.

1. Introduction

The clean code philosophy is seems be to emerged from the fundamentals of Software Craftsmanship. According to many software experts who have signed the Manifesto for Software Craftsmanship, writing well-crafted and self-explanatory software is almost as important as writing working software.

Following are the snippets from the book, show why naming is hard and disputable and the mindset to address this problem:

"The hardest thing about choosing good names is that it requires good descriptive skills and a shared cultural background. This is a teaching issue rather than a technical, business or management issue."

"Focus on whether the code reads like paragraphs and sentences, or at least tables and data structure."

2. Naming Conventions

2.1. Use Intention-Revealing Names

Basically, don't name a variable, class, or method which needs some explanation in comments.

For example:

int d; // elapsed time in days  

int s; // elapsed time in seconds

Can be named as:

int elapsedTimeInDays;  

int daysSinceCreation; 

int daysSinceModification;  

int fileAgeInDays;

2.2. Avoid Disinformation and Encodings

Don't refer to a group of accounts as "accountList," whereas it is actually not a List. Instead, name it "accountGroup," "accounts," or "bunchOfAccounts."

Avoid unnecessary encodings of datatypes along with the variable name.

String nameString;

Float salaryFloat;

It may not be necessary where it is very well known to the entire world that in an employee context, the name is going to have a sequence of characters. The same goes for Salary, which is decimal/float.

2.3. Make Meaningful Distinctions

If there are two different things in the same scope, you might be tempted to change one name in an arbitrary way.

What is stored in cust, which is different from customer?

String cust;  

String customer;

How are these classes different?

class ProductInfo  

class ProductData

How do you differentiate between these methods in the same class?

void getActiveAccount()

void getActiveAccounts()

void getActiveAccountsInfo()

So, the suggestion here is to make meaningful distinctions.

2.4. Use Pronounceable Names

Ensure that names are pronounceable. Nobody wants a tongue twister.

This

Date genymdhms;

Date modymdhms;

Int pszqint;

vs

Date generationTimeStamp;

Date modificationTimestamp;

Int publicAccessCount;

2.5. Use Searchable Names

Avoid single letter names and numeric constants, if they are not easy to locate across the body of the text.

grep "MAX_STUDENTS_PER_TEACHER"  *.java

vs

grep 15 *.java

Use single letter names only used as local variables in short methods. One important suggestion is that "the length of a name should be correspond to the size of its scope."

2.6. Don't Be Cute/Don't Use Offensive Words

deleteAllItems()

vs

whack()

vs

kill()

vs

eatMyShorts()

vs

abort()

2.7. Pick One Word per Concept

Use the same concept across the codebase.

FetchValue() vs GetValue() vs RetrieveValue()

If you are using fetchValue() to return a value of something, use the same concept; instead of using fetchValue() in all the code, using getValue(), retrieveValue() will confuse the reader.

dataFetcher() vs dataGetter() vs dataFetcher()

If all three methods do the same thing, don't mix and match across the code base. Instead, stick to one.

FeatureManager vs FeatureController

Stick to either Manager or Controller. Again, consistency across the codebase for the same thing.

2.8. Don't Pun

This is exactly opposite of previous rule. Avoid using the same word for two different purposes. Using the same term for two different ideas is essentially pun.

For example, say you have two classes having the same add() method. In one class, it performs addition of two values, in another, it inserts an element into a list. So, choose wisely; in the second class use insert() or append() instead of add().

2.9. Solution Domain Names vs Problem Domain Names

The clean code philosophy suggests using solution domain names such as the name of algorithms or the name of design patterns whenever needed, and use a problem domain name as the second choice.

For example, accountVisitor means a lot to a programmer who is familiar with the Visitor design pattern. A "JobQueue" definitely make more sense to a programmer.

2.10. Add Meaningful Context as a Last Resort

While there are a few names which are meaningful themselves, most are not. Instead, you have to place names in context for your reader by enclosing them in well-named classes, functions, or namespaces. If not possible, prefixing the names may be necessary as a last resort.

For example, the member variable named "state" inside the address class shows what it contains. But the same "state" may be misleading if used to store "Name of The State" without context. So, in this scenario, name it something like "addressState" or "StateName."

The "state" may make more sense in a context where you are coding about addresses when named "addrState."

3. Summary

Robert C. Martin says, "One difference between a smart programmer and a professional programmer is that the professional understands that clarity is king. Professionals use their powers for good and write code that others can understand." I hope this article will help you to be more professional and write clean code, for further reading refer to "Clean Code: A Handbook of Agile Software Craftsmanship."

4. References

1. https://cleancoders.com/
2. https://blog.cleancoder.com/
3. https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882/ref=sr_1_1?ie=UTF8&qid=1520625319&sr=8-1&keywords=clean+coding
4. http://manifesto.softwarecraftsmanship.org/#/en

Appendix

Manifesto for Agile Craftsmanship

As aspiring Software Craftsmen, we are raising the bar of professional software development by practicing it and helping others learn the craft. Through this work we have come to value:

Not only working software,

but also well-crafted software

Not only responding to change,

but also steadily adding value

Not only individuals and interactions,

but also a community of professionals

Not only customer collaboration,

but also productive partnerships

That is, in pursuit of the items on the left we have found the items on the right to be indispensable.