DZone
Thanks for visiting DZone today,
Edit Profile
  • Manage Email Subscriptions
  • How to Post to DZone
  • Article Submission Guidelines
Sign Out View Profile
  • Post an Article
  • Manage My Drafts
Over 2 million developers have joined DZone.
Log In / Join
Refcards Trend Reports Events Over 2 million developers have joined DZone. Join Today! Thanks for visiting DZone today,
Edit Profile Manage Email Subscriptions Moderation Admin Console How to Post to DZone Article Submission Guidelines
View Profile
Sign Out
Refcards
Trend Reports
Events
Zones
Culture and Methodologies Agile Career Development Methodologies Team Management
Data Engineering AI/ML Big Data Data Databases IoT
Software Design and Architecture Cloud Architecture Containers Integration Microservices Performance Security
Coding Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones AWS Cloud
by AWS Developer Relations
Culture and Methodologies
Agile Career Development Methodologies Team Management
Data Engineering
AI/ML Big Data Data Databases IoT
Software Design and Architecture
Cloud Architecture Containers Integration Microservices Performance Security
Coding
Frameworks Java JavaScript Languages Tools
Testing, Deployment, and Maintenance
Deployment DevOps and CI/CD Maintenance Monitoring and Observability Testing, Tools, and Frameworks
Partner Zones
AWS Cloud
by AWS Developer Relations

Naming Conventions From Uncle Bob's Clean Code Philosophy

Following this list of rules for naming variables, classes, and methods will help you write cleaner, more professional code.

Saravanan Subramanian user avatar by
Saravanan Subramanian
·
Mar. 15, 18 · Tutorial
Like (11)
Save
Tweet
Share
56.40K Views

Join the DZone community and get the full member experience.

Join For Free

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.

code style philosophy Software development

Published at DZone with permission of Saravanan Subramanian, DZone MVB. See the original article here.

Opinions expressed by DZone contributors are their own.

Popular on DZone

  • A Beginner's Guide to Infrastructure as Code
  • Building a Real-Time App With Spring Boot, Cassandra, Pulsar, React, and Hilla
  • DevOps vs Agile: Which Approach Will Win the Battle for Efficiency?
  • OWASP Kubernetes Top 10

Comments

Partner Resources

X

ABOUT US

  • About DZone
  • Send feedback
  • Careers
  • Sitemap

ADVERTISE

  • Advertise with DZone

CONTRIBUTE ON DZONE

  • Article Submission Guidelines
  • Become a Contributor
  • Visit the Writers' Zone

LEGAL

  • Terms of Service
  • Privacy Policy

CONTACT US

  • 600 Park Offices Drive
  • Suite 300
  • Durham, NC 27709
  • support@dzone.com
  • +1 (919) 678-0300

Let's be friends: