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.
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.1 Use Intention-Revealing Names
Basically, don’t name a variable, class or method which needs some explanation in comments.
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.
Date genymdhms; Date modymdhms; Int pszqint;
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
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.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.
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”
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 .
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:
That is, in pursuit of the items on the left we have found the items on the right to be indispensable.