A programmer who writes clean code is an artist who can take a blank screen through a series of transformations until it is an elegantly coded system.
—Robert C. Martin
In this article, I’ll be covering Robert C. Martin’s Clean Code, Chapter 2, Meaningful Names. This article highlights a few of my key thoughts, however, I definitely recommend a read as he also includes figures and examples.
How do I write Clean Code?
Before we can talk about clean code, let’s briefly cover messy code, harmful code, and the reasons why it’s the difference maker.
Bad code happens when we’re rushed, tired, or lazy. We know what our bad code is and when we’re writing it. Whether it’s formed from ignoring code smells or being under pressure—we can typically tell what’s going on. Bad code stops us from doing our job, it creates a constant cycle of stress and more bad code by ignoring principles detailed in this book and that I’ll cover shortly.
As the authors of our own work, it’s fundamentally important that we take care of our code. It should be tested, and read easily. “No duplications, one thing, expressiveness, tiny abstractions.” (Martin, Ch. 2) That’s it. But what exactly does that even mean?
Let’s start here:
Meaningful Names
The first lesson in clean code covers Names and Naming Conventions. Robert C. Martin repeatedly instills the importance of creating good names that have intention behind them. As developers, “We name and name and name.” (Martin, Ch. 2) While Robert creates numerous examples of why we should & should not name in a specific way—I’m only going to be detailing a few points that stood out to me.
When we write code, we want it to explicitly tell us what is happening. Rather than code that is implicit, meaning that when we read our code, we only understand it in the context that it was written. Let’s go over some meaningful distinctions that we will need to have:
- Eliminate Noise Words — these are meaningless and have no purpose. If you were to have two variables named ProductData and ProductInfo, understand that something like this creates confusion and ambiguity.
- Use names we can pronounce—we want to be able to talk about our functions and our variables so make understandable
- Use searchable names—this one is important. If the variable or function is going to be used throughout the project be sure to create something that is easily searchable and able to be interpreted correctly in & out of context. The variable userData may be intuitive on a ‘User Settings’ Component, however, when I pass that around the codebase to a ‘User Chat’ Component, userData could easily be confused as the user’s chat, their local time, even their contact list. The opportunity for confusion is endless. Here, try to use something like userProfileSettings.
- Pick one word per concept— pick one word for an abstract concept and stick with it. Rather than creating a fetchRecruiter, fetchNames, and retrieveUserProfileSettings. We like fetch here.
- We shouldn’t need the comments— We shouldn’t need to have a comment that explains what the variable is. We would rather have a variable that indicates what we have/what we are doing. This ensures that when we call for it in other places, we don’t get lost. currentAgeInHours works better than “h.”
For Class Names, such as for objects, classes, arrays, etc., try to use nouns or phrases that clearly indicate what the data is. This should not be a verb. Examples include: accountNumber, currentDate, employeeAddress.
While Method Names should include a verb. It’s important to describe what is taking place in the function accurately. Examples include: deleteContact, fetchUserProfileSettings, and submitForm.
