What’s in a Name?
April 28th, 2006I recently wrote about Easy Programming, my pseudo-methodology for “keeping going” in the face of difficult or tedious tasks. Since then, I’ve observed an aspect of my workflow that, while seemingly among the easiest of tasks, can be the most limiting to my productivity. What is this devastating conundrum? The challenge of naming code.
I must have a christening hang-up. I get all cold-footed when the time comes to name a class, source file, method or function. Even variables! There’s a lot of pressure to come up with a name that is both instantly descriptive of the concept being represented, while also compatible with the prevailing code style, easy to pronounce, type, etc.
Could it be that the most mundane task, giving names to the commodities we trade in, could be the hardest aspect of programming?
In light of my recent thinking on Easy Programming, I was inclined to think that the best solution is to just forge ahead. Don’t let myself get caught up in such antics. If I can’t think of a class name within 5 minutes, just call it something and get on with the show. After all, after everything is working, I can always rename it if I feel strongly about it. I was getting happy with this conclusion when Jonathan Wight of Toxic Software made a statement that tipped my thinking in the other direction:
“Generally if I can’t think of a name for a class it means that when i come to refactor the code that the class wasn’t well thought-out in the first place.”
Well, shucks. That sounds downright obvious now that I’ve heard somebody else say it.
Zachery Bir pointed out that such thinking is common in OOP circles. A bad name is often identified as a code smell – something that stands out in code as a sign of potential lurking problems. An article on good naming supports exactly what Jonathan was getting at – that a badly named entity begs for refactoring.
So the dilemma becomes this: how do I keep my job easy, and name things correctly, and avoid spending an eternity doing it? My conclusion is that naming is important enough that it deserves a good length of consideration. Don’t be afraid to give yourself an hour or more! Do other stuff and let it sit in the back of your mind. You’re not wasting time. What you’re doing is designing on autopilot. When you think of the right name, it will serve as a specification for what you need to do – and specifications lead to easy programming. If you can’t deduce the right answer yourself, seek help from coworkers or the web. The articles on the C2 Wiki, including those cited above and this one on “meaningful names” go into detail about some techniques that might help you settle on the right name. There’s gotta be a right name for the class. What does it do? What should it do?
Sometimes you simply won’t be able to figure it out. A programming defeat, and it stings! At last it may be in your best interest to follow my first instinct: simply forge ahead. If you know you can get the job done and fix it later, your time may be better spent on future refactoring than on present-day moping around, trying to come up with the perfect name. Use your failure as a exploratory design experiment. It’s OK, you failed. We all do it. But whatever you do, don’t waste your time trying to come up with some “almost appropriate” name for your mistake. Don’t fake success by giving it some prestigious name that blends into the background. Name it SmadoodieCracker, or GodDamnImASuckyProgrammer, or something equally delightful. Better yet, pick a standard template and name all of your cop-out classes using this scheme: SuckyClass001, etc. Now you can do a global search for your smelly names.
Many programmers will feel hesitant to adopt such a practice. Your self-esteem is not fully developed, and you fear that coworkers will see what a fraud you are. Surely your boss will decide that you’re not senior developer material after all. And here we thought you were an infallible genius! This all may be true on a sucky team, but on a good team they’ll appreciate your candidness. And when browsing the sources to SmadoodieCracker, should inspiration strike and present a clear vision of what the class should do, they won’t think twice about overhauling your ugly mess. You owe them a beer, now.
Other people fixing your code? The easiest programming of all!
April 28th, 2006 at 8:16 pm
You have problems naming variables too? You must have had a punctillious CS professor like I did. I remember endless lectures about integer variables must have descriptive names starting with IJKLM, and floats start with ABC etc. This is apparently an old Fortran supersition (that’s when I learned it, when I took Fortran).
I remember being so irritated with these naming conventions that I did all my assignments with variables of a single character, like “I.” The professor insisted that I must use full names for all variables, and made me rewrite the program. I changed I, J and K to Inez, Jane, and Kate. He didn’t like that much either.
April 28th, 2006 at 9:21 pm
While having trouble naming things is, indeed, a code smell, I do not think that should stop you. In fact, if you do not see an obvious name, your best bet is almost certainly to proceed, then see what you ended up writing.
Go ahead and name it ‘GarbageBagClass’, then move on. After you implement it, you will almost certainly have a pretty good idea of what the class ended up doing. Refactor it at that point, as you can then split it up with a much, much better idea of what the functionality should be. Put another way, the lack of clarity in your mental model that is causing you naming trouble may well be best addressed by working with the code and design.
You do not want to leave a GarbageBagClass lurking in your code, of course, but if a quickly chosen name can let you get to a prototype by the end of the day, you are more likely to refactor it well.
Scott
April 29th, 2006 at 4:14 am
I think the difficulty of naming things depends a lot on the tools you choose to, or have to, use. For instance, I worry prematurely about naming issues only when I work on client projects using either a) CVS for version control, and/or b) static, compiled languages.
With projects managed through CVS, or with legacy code bases having other similarly limiting constraints, changing file names and refactoring & reorganizing the code becomes enough of a headache that it pays to get it right (or mostly right) the first time around, whenever possible. This thankfully ceases to be an issue with modern tools, like Subversion or Darcs, that are able to move files and directories around in the repository with their full revision history preserved.
Again, with static languages, the cost of changing one’s mind often becomes high enough that a certain non-trivial amount of premeditation and planning may be warranted. That’s why I much prefer to work, when I can, in dynamic languages (such as Ruby and Scheme), where code can be naturally written in a bottom-up fashion, and a mere prototype can evolve, through lots and lots of low-cost refactoring iterations, into the actual first version of the program. It’s liberating enough that I’ve learned to never worry about trivialities (such as naming), knowing I can change my mind at any time.
Now, as for naming a product or a company, that’s a showstopper indeed – speaking as someone who has spent way too much time checking domain availability and huddled up with Latin/Greek/Finnish/etc dictionary ;-)
April 29th, 2006 at 7:23 am
Charles: I did have some picky CS professors, but most of my education happened at Apple, where they thankfully subscribed to some pretty good naming habits. I would have to agree with your professor that single characters are not great for variable names. In fact, I usually avoid even the common shorthand of naming for-loop iterators “i”. If you decide to search/replace on names like that it’s a nightmare. Therefore, my for-loops usually involve the clumsy “iterator” variable.
Scott: Good point and I think it supports my “if you fail, forge ahead” idea. But I do think at least a little bit of time thinking about what the ideal name would be can help prevent a lot of refactoring later.
Arto: The tools problem is a great point. I can totally relate to the CVS issue, and I think my file-naming phobia stems from spending so many years using that crappy tool :) Since I’ve switched to subversion I find myself actively reminding myself that it will be no big deal to even rename a file or move an entire directory. Definitely helps with flow.
April 29th, 2006 at 10:57 am
Well, to be fair, the old conventions like naming iterators “I” come from the days of punched cards, when longer variable names might cause single lines of code to exceed the length of a punched card, and more typing (actually punching) meant more likelihood of errors. Just be glad, very glad, that you didn’t study programming back in the 1970s. Or even worse, in the 1960s, here is an amazing example of a 40 column Hollerith Card that you filled in with a #2 pencil. I actually used these cards to write FORTRAN programs.
April 29th, 2006 at 3:34 pm
Did Apple do anything about automating the naming/identification process?
We’ve now got free SQL engines… yet programmers are still wrestling with having to make up “good names” at the point of creation.
April 29th, 2006 at 9:10 pm
Do *not* name your classes SuckyClassFOO. What happens to the other poor sap who has to look at your code? If you don’t like the class leave a /* XXX refactor this class */ comment.
April 29th, 2006 at 9:30 pm
I agonize over class, method, ivar, and application names all the time. To me this goes along with having, or at least working toward, a crisp idea of what I’m trying to accomplish and how I’m accomplishing it. Naming reflects how well my logic is factored and therefore how conveniently it can be subclassed. And it affects how clear and consistent the documentation will be. These issues are important to other programmers who will read my code (and I treat my future self as an “other programmer”).
I want to be able to do global search-and-replace operations when I decide to rename something. Even without replace, global search can be useful. So I use naming conventions like two-letter prefixes and typographic conventions like leading underscores.
Another kind of “search” issue is “googlability.” Not only do I want people to be able to find my app via Google; I also want to be able to do vanity searches to see what people are *saying* about my app. I often wonder if I could have thought of a nicer name for AppKiDo, but in any case it is trivial to find with Google. I had an idea once for an app that I would have loved to call “BRANE,” for “BRowse, ANnote, and Edit,” but it turns out that word has a special meaning to physicists. (I never did write that app — it’s still on my mind, though.) Right now I’m working on a very small tool that I’m currently calling “Xcop,” for “Xcode project-file,” but it turns out that is not very googlable.
April 29th, 2006 at 10:27 pm
Taybin: Yeah – to be honest as soon as I posted this entry I had second thoughts about the perhaps dramatic advice to name things super-strange as a marker. I still kind of like the pure honesty of it, but I agree that it’s probably not very useful in a large group environment. I would probably do it in my own code but not in a shared repository. Your suggestion to just leave self-effacing comments nearby is probably a better choice.
Andy: An interesting point – connecting the naming conundrum to googlability. It’s true that what you identify is yet another christening problem we face as developers. NAMES! Arrrrr!
April 30th, 2006 at 6:04 am
I wouldn’t worry about commenting a class that you think the class name might be renamed in the future. I’d spend time to think about what you are going to name the class, but if you cannot get the perfect name, use the 2nd best and move on. Usually, even the names that you expect to be perfect might in the end be renamed as you learned more about the innards of your app. I like to expect that the names of all my entities are subject to change and that doing so is perfectly natural and “the right thing to do”.
I think what is most important is that you keep your design flexible to allow yourself the ability to change the names of classes, methods, variables, etc as it becomes appropriate. Having the right tools to do this (like subversion) as well as good refactoring tools definately helps.
Is there a refactoring tool for Xcode?
May 2nd, 2006 at 10:02 am
I tend to get stuck on names only when a critical design is involved. That gives me loads of time to come up with a name for the class I’m designing on paper (or in Omni Graffle or whatever) before I wrote code. For less important classes I just pick a name that seems reasonable so I can get along. My stressing about names is reduced (and I do stress about it, too) because I have no problem with making massive changes to rename classes, methods and variables. The only time it becomes critical for me is when I have written code coworkers are interacting with often, and even then I’ll rename, often when I refactor other unrelated items (renaming is a simple kind of refactoring, I hope) A good refactoring tool will make renaming even easier than global search. I don’t know of any such tool for use within Xcode, nor for Objective C. There ought to be some free-standing tools for C++.
May 5th, 2006 at 7:15 am
Yeah it seems the refactoring tools are really a missing bunch on Mac OS X. Perhaps this is a good business opportunity for somebody!