Get to Honest (Article 3)
5 minute read
We have a thing with a name. But its name is obvious nonsense.
One of my more gnarly experiences was when I worked within a system that spoke to the FAA’s system. This particular method was named PreLoad(), telling me when the system calls the method (not very useful). The problem is that there is a missing name. Nothing tells me what would happen on PreLoad().
Based on Article 2, I then extracted the entire body of PreLoad() and called it Applesauce(). At that point, the code explicitly says that upon PreLoad(), do Applesauce().
Now we want to make Applesauce() honest.
Making the Name Honest
I want to make the name honest. It doesn’t need to be completely honest. It just needs to tell me one honest thing. I look at the method to figure out one thing that appears to be key to its execution. I just read through the body and see what appears central.
Part 1: Look inside the body
Focus on inside the body. Look for patterns that repeat here or between this and other methods.
I find it useful to look for variables that are system components (“database,” “screen,” “network,” “service”), look where the return value comes from, and see if something is used many times.
Part 2: Look for one thing the code does
As you look for simply one thing that the code inside the body does, consider also the judgment of how easy it will be to work with, how safe it is, or other useful traits.
In the example, I noticed that there was a global named db that was used a lot. Several places created recordset objects, set values, and read or wrote them using the db. Since it mixed reads and writes, I named the method probably_doSomethingEvilToTheDatabase_AndStuff().
As a name, doSomethingEvilToTheDatabase() is “interesting” enough. Why would I also write probably_ and _AndStuff? I wasn’t certain what the method does, but I had found one thing, and frankly, wasn’t 100% on that one. The probably_ informed my team that I wasn’t certain that it does the one thing I was saying it does. The _AndStuff informed my team that this name needs more iteration. It’s honest, but not complete.
Meanwhile, it is honest in several ways, recording several insights that I had.
- The main effect of the method seems to involve the database.
- I don’t yet understand what it is doing to the database.
- I am getting all judgy about how it is treating the poor database. I don’t like it.
- It does more things that I don’t understand at all.
The last three insights are as important as the first. Even if I wandered away at this point, a future reader of the code would have some insight. They wouldn’t know what the method did, but they’d be properly wary of it.
They’d know that no one knows exactly what it does, it does that thing to the central database, and the last person to touch it thought it was doing some nasty stuff. Good! I’ve transmitted all the knowledge that I have about this method. I’ve put them in the proper frame of mind for working with it.
Part 3: Write down by renaming to a better name
The components necessary for this better name includes two things:
- One honest thing it does; and
- Clarity about what we don’t know yet.
The way you perform the renaming is important. Don’t just edit the name; use a rename refactoring. When we edit the name we have a chance of accidentally changing behavior in some way, but when you use a rename refactoring, you ensure safety.
Be specific!
The most common way to screw up at this point is to be too general in your name. Being specific is good!
The intent of naming in this way is to allow a reader to understand a chunk of code without looking at it, just by looking at the name for that chunk of code. That reader needs specific detailed knowledge. So the name has to be specific.
For example, I could have named my function handleFlightInfoSomehow(). That would have been honest, but it hides the potential risky thing done to a very important part of the system. Thus doSomethingEvilToTheDatabase is more specific as to the risk.
Looking ahead just a bit, the next step will be to make the name convey everything the code is doing (be Honest and Complete). If we are specific, then the only route to completeness is to add to the name. I keep the same precision but add more description.
If I am overly general or imprecise now, then it most or all of the things the function does will be already roughly describable by the name. This will make it a lot harder for me to see the things that aren’t yet conveyed in the name, which will make it harder to create a name that fully describes the code behind it.
Not just for functions or nonsense names
This step applies when naming classes or variables as well as bad names that are not yet obvious nonsense. Common bad names for classes are anything that ends in -Manager or -Operations. Poorly named variables are usually named the same thing as their type.
In either case, we need to have one insight into this thing. What is one important responsibility of the class? For a variable, what differentiates this one Foo instance from all the other Foo instances that might be out there? How does the code using the variable think of this one? Whatever that insight is, write it down.
Adopt Now
Help your team adopt Naming as a Process now!
Read More
Next up: make how our basically honest names become completely honest.
Or read the whole Naming as a Process blog series.