I participated in a code review yesterday, and while there were many things I wanted to say, I only think of the right thing to say an hour after it’s all over. What I wanted to say was
The most important thing you can do to improve the quality of your code is to choose good names.
At least, that’s the way I feel right now. I reserve the right to change my mind tomorrow.
It’s really important to remember that naming is not just an action you apply to passive code. The goal of good naming should drive your design and your coding in much the way that Test-Driven Development’s goal of writing tests first is supposed to drive your code design.1 In fact, this practice of active naming so important, I think that it deserves a name — Name-Driven Development. Anyway, here are some advice on naming methods.
Choosing Method Names
- If you can’t choose a good name because the method is too long, then slice up the method into smaller methods that you can name.
- If you can’t choose a good name because the method is doing several things at once, then divide up the responsibilities into other methods you can name.
- If you can’t choose a good name because you don’t know what the method is doing, refactor out small parts of it that you can name well, and then maybe a good name will come to you.
- If the method is correctly named but seems like it is out-of-place, then it probably is. Move it to another more appropriate place in the code.
- If the method is correctly named but the name is too long (such as “savePreferencesWithoutPrompt”), then refactor the code so that the method can have an appropriate shorter name.
- If you can’t choose a good name and you don’t know why, then that’s a code smell. Take the time to figure out why the code smells bad and fix it so you can give the method a good name
I’ve only listed naming considerations for methods above, but naming principles for classes and variables have a lot of overlap with naming principles. Core to the practice of active naming is that a good design should have good names, and that if the names aren’t good, it’s a sign of problems in the design.
Your Names Tell a Story about Your Design
The big picture to keep in mind when you’re choosing names is that the names you choose tell a story. Here’s a mind exercise you can do to help you see that story. Take your code and remove all the comments and all the code body, leaving just your classes, the class fields, and the method signatures. That’s the big story that you are telling with the code. The stuff in the methods that you deleted? Those are details — important details, sure, but still just details. So, look at what remains — your code story — and see how your names are helping you tell the story. Put yourself in the place of the reader of your story. Ideally, your story should be enough for someone who has never used your code before to understand your code, use your code, and fill in its details or embellish the details if they want to. And if the story isn’t enough, rewrite it until it is (or until your boss tells you to stop working).
That’s it! Happy story-telling with code.
1 I actually think that virtually all of Test-Driven Development’s design benefits can also be derived from Name-Driven Development. Of course, you don’t get the tests, but you get a deeper appreciation of the principles of design.