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 ( http://manifesto.softwarecraftsmanship.org/ ), 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 mind-set 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 & encodings

Referring a group of accounts as “accountList”, where as it is actually not a List.  Instead name it as “accountGroup”, “accounts” or “bunchOfAccounts”.

Avoid unnecessary encodings of datatypes along with variable name.

String nameString;

Float salaryFloat;

It may not be necessary, where it is very well known to the entire world that in a employee context, the name is going to have a sequence of characters.  The same goes of 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 these classes are different ?

class ProductInfo  

class ProductData

 

How do you differentiate these methods in the same class ?

void getActiveAccount()

void getActiveAccounts()

void getActiveAccountsInfo()

So, the suggestion is here to make meaningful distinctions.

2.4.Use Pronounceable Names

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

This

Date genymdhms;

Date modymdhms;

Int pszqint;

vs

Date generationTimeStamp;

Date modificationTimestamp;

Int publicAccessCount;

 

2.5.Use Searchable Names

2.5.1 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

2.5.2 Use single letter names only used a local variables in short methods.  One important suggestion is here

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

2.6.1

holyHandGrenade()

vs

deleteAllItems()

2.6.2

whack()

vs

kill()

2.6.3

eatMyShorts()

vs

abort()

 

2.7.Pick One Word Per Concept

Use the same concept across code-base.

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

2.7.2 dataFetcher() vs dataGetter() Vs dataFetcher()

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

2.7.3  FeatureManager  Vs FeatureController

Strict to either Manager or Controller.  Again consistency across code base 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.

Eg. For example, if 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 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 suggest to use solution domain names such as name of algorithms, name of design patterns whenever needed, and use problem domain name as the second choice.

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

2.10. Add Meaningful Context, as a last resort

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, use 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 scenarios name it something like “addressState” or “StateName”.

The “state” may make more sense in a context where you 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 helps you to be more professional and write clean code, for further reading refer [3].

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

A Appendix

A.1 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.

Advertisements

1 thought on “Naming Conventions from Uncle Bob’s Clean Code Philosophy

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s