5 Tips On Naming Variables From “Clean Code”
Variables are one of the most important aspects of your code, so they should be easy to write, right? Right… (*sarcasm*)
As a self-taught developer, I’m constantly on the lookout for resources respected by the industry. Good books are like charts that help you map out your course on the ocean. You could maybe make it without them using your wits, but it’s a lot easier to have something to tell you if you’re headed in the right direction!
Lately the aspect of coding I have been most interested in learning more about has been — everything. After doing a number of problems on exercism.io’s Python track and working through some scripting with Automate the Boring Stuff, I wanted to take a step back and not only consider what I was coding, but how I was coding it. Were my functions and classes following industry-accepted best practices? Experienced coders will probably laugh at that idea, but remember that I’m relatively new at this and incredibly naíve.
Enter Clean Code, by Robert C. Martin. In my internet travels, this book has been consistently recommended by the vast programmer hive mind, so I knew when I had some free time I would have to give it a read.
I’m still working my way through this 400 page monster tome, but I can already say that it is pretty awesome and delivers!
After some introductory pleasantries, Chapter 2 dives right in on the subject of naming. Variables should be easy to name. After all, we do it many, many times over the course of a program. But as a developer, have you ever taken a step back to consider if you’re naming your variables correctly?
How do you know if you’re naming your variables correctly? Well, does your code tell a story?
Again and again in this book, Martin harps on telling a story with your code. He makes it look so easy in his examples, and it’s something I’m striving to do. Telling a story means other people reading your code should be able to understand everything they need to by just reading your code. By naming the variables and functions correctly (among a few other things) you can craft code that reads like an article or a blog post, as opposed to weird alphabet soup that needs to be pulled apart and debugged.
Here are a few of Martin’s tips on how to “correctly” name variables and get the literary code we’re looking for:
Intention-Revealing Names
Naming variable shouldn’t be like naming a dog. It’s not like: “this seems like a ‘y’, let’s name it ‘y’”… good names should leave clues as to your intent with the program, or better yet point to that intent with a bright yellow, flashing sign. Instead of naming a list li, which I confess I have done too many times to count, how about naming it gameBoard, or userList, or whatever it is that you’re trying to accomplish with that variable?
The name of a variable should tell you why it exists, what it does, and how it’s used.
Distinguish Differences
This one hit really close to home. What’s the difference between ProductInfo and ProductData to the average reader of your code? If you guessed nothing, you’d be right. But at this very minute, those are the names of two discreet variables in a python program I’m working on. This needs to be reworked.
If you need to create separate variables for different purposes, the names should be reflective of those differences and what you’re using those variables to do.
Non-Searchable Names
This is a tip that is meaningless now as I’m writing code that’s less that 50 lines long, but I could see it paying off big time with longer projects. Suppose you name your variable t for time, then you write a fancy 500 line stopwatch program… then you decide you want to rename your t variable to be something clearer. It could be super painful to try to sift through the program for every instance of the t variable. But if you name variables something that is memorable and/or easily searchable, you get to avoid this problem.
Naming Classes vs. Naming Methods
Classes should be nouns, methods should be verbs. It’s as simple as that. Classes exist to store data, while functions exist to manipulate said data. So this basic guideline is super valuable to someone like me who is relatively new to Python. It helps me both to have a strategy for naming classes and also to decipher what my classes are doing in code I’ve written but am revisiting after a while and am unfamiliar with.
The chapter includes tips on other pitfalls, like unpronounceable names, encodings and names that aren’t searchable, but I found those first few hints to be especially valuable.
Of course, this chapter hasn’t solved all my problems. Naming is still something I struggle with a lot. I wouldn’t be reading the book if I didn’t. But being conscious of the importance of this step is at least part of the battle. It’s also interesting to know that even experienced developers deal with issues around naming too. I imagine I’ll be revisiting this chapter of the book several times in my career for its fresh (at least to me) insights.
