Good Names

Imagine a door with an unusual handle. The handle is five feet off the ground and rotates upwards to open the door. The door has no lock. Is this a good door design?

Sorry. That’s not an answerable question. The purpose of almost every door is to prevent something from going through it without preventing everything from going through it. Some doors exist only to mitigate heat loss while allowing anything else through. Some doors exist to keep everyone out except authorized personnel. The goodness or badness of a door design depends entirely on how well or poorly it performs the task of preventing undesired access and allowing desired access.

If I were describing a jail cell door or bank vault door, that would be an absurdly bad design. But for the teacher’s supply room in a kindergarden classroom, it’s pretty good. It doesn’t prevent access to any adults, but the kids are unlikely to be able to get through without adult supervision. Purpose matters.

Last time I talked a bit about what makes a book title better or worse. These ideas can be extended to naming just about anything, but it is important when considering the goodness or badness of a name to keep in mind the purpose of the name. Frequently when we name types and methods, it’s like my book example. The purpose of the code, like the purpose of the book, is to provide a benefit to the consumer. The purpose of the name is usually (*) to make it easy for the potential consumer to find the thing, and then quickly and accurately evaluate whether it is likely to provide the desired benefit.

With those purposes in mind, here are some guidelines that I use when trying to come up with a public name for something:

• Everything in my Bad Names post.

• The name should describe what the thing is (classes) or does (methods) or is used for (interfaces), as opposed to how it achieves any of those things.

• Names should describe the unchanging aspects of the nature of the thing.

  A small example of how I got this wrong recently: the style that I use for adding responses to comments in this blog is called “yellowbox”. If I ever decide to change it the look of the blog and want to make it blue, I’m going to look pretty silly having a style called “yellowbox” that draws a blue box. I should have called it “response”; it’s always going to be for responses.

• The name should use the vocabulary of the consumer, not the jargon of the mechanisms used in the implementation.

• The name should be as unique as possible, so that searching for the words in it rapidly narrows the field down.

• The name should be as precise as possible.

  How many “HandleSomething” methods have you seen? Usually these do something a lot more specific than “handling”. It might be important to the consumer to have a better idea of what you’re doing in there.

• The name should not have any non-standard abbreviations; FindCustRec is unlikely to be found by searching for “customer” or “record”.

Those are just a few off the top of my head. What are some of the criteria you use to come up with good names for types and methods?

**************************

(*) There are unusual cases where names are deliberately chosen to work against those typical goals. Sometimes code is very special-purpose, designed to be used very rarely and then only by subject experts. In those cases, you do not want the code to be accidentally found by people who are unlikely to need it, and unlikely to use it correctly. In those cases, it’s desirable for the name to be laden with the jargon of the experts who will be using it. Doing so sends the message to potential users “if you do not know what these words mean, you probably should not be using this code”. Again, purpose matters.

Comments

• Anonymous
  April 06, 2009
  >> I should have called it “response”; it’s always going to be for responses. That might be true for an individual blog page, but it's a dangerous statement to make when dealing with any site of reasonable complexity.  What if I write something really profound and thought-provoking, and you decide to apply your special style to it to make it stand out for other readers?  Also, the name "response" is just too generic - response to what?  The text I'm typing right now is a response to the article, but that's not the same thing as the text you might write in response to this comment. I would probably go with "highlightedCommentText", but the flexible and reusable nature of a CSS style makes it really hard to choose good names.  If you later decide to apply the style to certain sections of article text, then highlightedCommentText would become a bad name, too.

• Anonymous
  April 06, 2009
  @ Joe In keeping with the "vocabulary of the consumer" guideline, "response" specifically refers to the author's responses to comments. Sure from your point of view the "comments" are responses to the blog, but only Eric sees that style name; he's the consumer, so the vocabulary comes from his point of view. A guideline I follow for naming is "Don't be afraid to make a name too long.". It's far easier, to my mind, to later identify an overly-long name and think of something better than it is to later find an overly-short name and try to figure out what it means. If you really must end have short and cryptic names for things, you can always run an obfuscator over it later ;)

• Anonymous
  April 06, 2009
  Personally, I 100% agree with everything said about the good names: they should describe the purpose of the thing, using the consumer's vocabulary. I can envision someone offering an objection that sometimes, some 'things' have multiple purposes from the consumer's perspective, but I believe this can always be worked around, using clever phrasing and a broader view on the 'thing's' purpose. The fun starts, however, in the following situations:

• When the champions of the 'old-school' C++/UNIX school clash with 'pro-Microsoft' crowd: i_am_sick_of_code_wars() vs. IAmSickOfCodeWars();
• When the developers don't speak English; in that case, the difference between FUNCBREC and StatementBindingContext is not clear, to put it gently: both are just some barbaric nonsense. :-) Also, what about the Hungerian notation? I know it was useful in the early Windows days, when half of the system was written in the Assembler language and the name was the only way to know the 'thing's' type; later, in the MFC days, we have seen constructions like m_memberName; now, in the days of SharePoint, we see, for example, SPAlert, for a class name... Along with its namespace prefix, it would look quite good as simply 'Microsoft.SharePoint.Alert' to me, but without the namespace prefix..? How may various 'Alerts' can there be in the code? And if we go 'SharePointAlert', then how long before we get 'VeryLongNameThatTakesAgesToTypeAlert?' On the other hand, the prefix 'SP-' may suggest 'SharePoint' for some people, and, say, 'Starting Point' for others... In short, I believe the art of naming is a bit like the martial arts: don't use the techniques, use the principles. And, as I have already said, I agree with the princilples from the post. Thanks.

• Anonymous
  April 07, 2009
  For methods I use a rule of thumb that says, "Given a method's name, signature, and return type you should be able to write a test without looking at the code".  I'll be pointing other developers to this and the Bad Names post for guidelines on how to get the name right.  Thanks for both posts!

• Anonymous
  April 07, 2009
  I live in venezuela. And I found this blog almost by accident I have a coworker who totally adores cryptic names that mean something only to her. For instance: Id from user that writes this blog string bidusuye; what about their name? string busun; .... I mean.. What? I have argued so many times to not use those horrible names but she won't let go of her insane nomenclature, i don't even want to touch the matter with the method names, they are insane... I for one, like to use names that are descriptive for example UserRegistration() for a method. But I like your guidelines and I think I'm going to print these, translate them into Spanish (that's my main language, no one speaks English 4 miles from me) and put them in big font letters, and pray they become a kind of rule Of course, only if you mister don't mind. May I?

• Anonymous
  April 07, 2009
  Names of functions should generally be action-oriented. Functions do things, and their names should tell what they do. For example, instead of UserRegistration(), it would be clearer to call it RegisterUser(). That also forces you to think about the actual steps involved in registering a user. On another note, I think boolean variables are one of the toughest kind to name well. Having a good handle on grammatical tenses helps a lot. Booleans describe a state. Understanding what state an variable has had, has right now, or will have in the future determines its use. I think booleans work best when they are used in the present tense. Eg bool keepGoing vs bool gasPedalIsPressed I recently rewrote a small portion of code. It changed the way I thought about the way it worked and I ended up refactoring it as well. I was able to spot the deficiencies just by trying to give the variables more meaningful names. (I wrote about it here: http://ryan.kohn.ca/articles/making-code-more-readable-an-arduino-example/)

• Anonymous
  April 07, 2009
  The comment has been removed

• Anonymous
  April 08, 2009
  @Denis, While you're on the right track with your Sharepoint.Alert, I've seen people create entities called Image or File which really mucks you around when you need to import System.IO or System.Drawing.Image and System.Web.UI.WebControls.Image. NameSpaces are good, but it's sometimes quite handy to create a convention. 6 of one, half dozen of the other, you get burned either way.

• Anonymous
  April 08, 2009
  The comment has been removed

• Anonymous
  April 09, 2009
  "as opposed to how it achieves any of those things." Putting the HOW in a method name can make sense for private functions, if, for example, a particular job is accomplished differently depending on context.

• Anonymous
  April 10, 2009
  I believe that vocabulary should be dictated by or strongly connected with the problem domain. For instance, if we describe the door "lock" is a good term. It resides in the door problem/purpose domain. On the other hand we can name it "shiny metal thing", descriptive but taken from much broader domain. In big software projects it is often hard to find adequate names that were not used before. The scope of problem domain narrows the words usage. Thus makes developers use prefixes and suffixes to spawn new words: BasicAuthentication, ComplexAuthenticaion or BTree, BTreeEx etc.

• Anonymous
  April 14, 2009
  The comment has been removed

• Anonymous
  April 21, 2009
  I hate to be too literal, but I chuckle when I see a door with a sign on it that says "This door must remain closed at all times". At "ALL times"???  Why is it a door, then, and not a wall?  If it must remain closed at all times, the door doesn't need to be there at all, and it should be plastered over!

• Anonymous
  April 24, 2009
  You won't look silly if you change your stylesheet to have .purpleText {color:#000;}

• Anonymous
  May 29, 2009
  The comment has been removed