When Programming, You Must Name Things


hello-my-name-is-sticker

Programmers can spend a lot of time worrying about, thinking about, and optimizing the way that the code they’re writing looks. Whether it’s language designers obsessing about the way that you’ll find the length of string or language-users sweating about whether the function should be called findClassById() or get_class(), all thinking about naming is arguably a colossal waste of time.

After all, we all know that the programmer’s interpreter — a computer — doesn’t really understand the name of the function in the way that the writer of the program does, so (in one way of thinking) it doesn’t make a lot of sense to sweat the details too much. Just get it to work and then use it forever. So if you’re making a Zip archive with a function called zip() or the function createZipOfNestedFolderStructureFromTopLevelFolderFilePath(), it doesn’t really matter. Both take the same input, both do the same thing, and one is even like 1000 characters shorter than the other. Typing efficiency between the two makes the shorter zip() about 1000 times better. Right?

Brevity vs Explicitness

At a language-level, optimizing for typing simplicity means favoring func to the longer but more explicit public static function. In “user-land” it means building a simple command like findGroup over the more explicit findGroupByUrlSlug.

As the above names hopefully suggest, there are two basic goal we can have in the naming of variables, functions, classes, methods, or anything else in a program. You can aim for typing speed and simplicity or can try to be painstakingly thorough and exact.

At a language-level, optimizing for typing simplicity means favoring func to the longer but more explicit public static function. In “user-land” it means building a simple command like findGroup over the more explicit findGroupByUrlSlug.

Languages naturally fall into different places on this continuum. More high-level, dynamic languages like Ruby or Python has a tendency toward a shorter and less explicit syntax because they don’t require declaring your variable type (float, boolean, integer, string, etc) and allow for more operater overloading (using + for things other than addition, for example) than other languages.

Lower-level (that is: close to the memory-allocation) and staticly-typed languages typically require more explicitness. Because all variable’s type of value must be declared up-front, but also because that kind of behavior typically makes people name more clearly. The grand-daddy of explicitness, in my limited experience, is Apple’s Objective-C, where most of the commonly used libraries have names, at least in the common parody, that rival my earlier createZipOfNestedFolderStructureFromTopLevelFolderFilePath() example.

xcode-objective-c

Quick glance of Objective-C in Xcode

There’s much to be said for Objective-C like thoroughness in naming. It makes it clear to the human, if not the computer, what’s really going on. Assuming that the name is long for greater descriptiveness (and not mere sadism), you can avoid a lot of trips to documentation with some good explicit names. For example, what you’re going to pass to a function named simply zip(), if it will take any argument at all, is hard to guess. When a function says it creates a zip of a nested folder structure when passed the file path to the top level folder is pretty dang clear. But it’s also a pain to type and much harder to recall after you’ve not used it for a while…

The Roles of Teams and Tools in Naming Conventions and Preference

One of the simplest and most powerful determiner’s of one’s preference for simple short names and longer more explicit ones is the tools that you’re expecting to have, and how you’re expecting to use the variables and function names. If you’re thinking about how you’re going to type all your names from scratch a lot, you’re going to think it’s almost barbaric to have to type more than twenty characters to do something common. While I like the idea of my comically-long zip() alternative, coding using it in Window’s Notepad or some other really simplistic editor would be an insane exercise of torture. (On the bright side, you’d probably find some pretty good clipboard copy-and-paste manager…)

If you’re thinking about how you’re going to type all your names from scratch, you’re going to think it’s almost barbaric to have to type more than twenty characters to do something common.

microsoft-visual-studioIf you’re expecting to have an autocompleting integrated development environment like Microsoft’s Visual Studio with it’s “Intellisense” (that is essentially, a really fancy word processor), you’re more likely to like the explicitness that longer names provide. After all, so long as you get a few characters that are somewhere in the name of that function, you’ll probably be able to fuzzy-match your way to the function you were actually looking to use by pressing an arrow key a few times.

Another factor driving how you name is the question of the coding standards of the group or team you’re working with. When a team has decided that there should be a hard character limit of about 60 characters on a line, names that come closer to that are likely to feel frustratingly verbose. But if your team always works in an IDE and has collectively decided that “soft” word-wrap is a gift from technology, they’re a lot less likely to balk at your 60-character method name.

A similar kind of influence is likely to come around the stated preference of the most powerful people of a given team, and the expectations the team has for how quickly they’ll need to travel around the entire surface area of a codes base. A team powered by a single well-respected developer with a strong preference will likely default to her preference. But if the team is large and each of them regularly touch all the surface area of a code base, they’re likely to fight for a while and then settle on some sane standards they all like.

How specialized the working methods of the team are matter too. If everyone owns a small corner of a giant code base, and there’s no peer-review (in the form of regular code review, pair programming, etc), each can and quite possibly will do pretty much do whatever they want. When I’m alone and the only user of zip(), whatever I want its name to be it can be. When everyone regularly uses it and expects it to behave in a way they think it should, it’s more likely that its name gets a bit more explicit.

So, How Do I Name Things Well?

You thought I’d have a pat answer for “what’s best?” Sorry, but I don’t. Naming is an exercise, more than anything else, in being sane and rational and understanding all the trade-offs you’re making. Short quick names are great, but they increase the likelihood that someone later will think that zip() takes a list of files and not a prearranged-on-the-disk folder which it’ll walkthrough and recursively pack. Longer names that specify the parameters of the function in their name avoid that problem, but they cause hand-cramps or huge quantities of documentation-examination and copy-and-paste for people not using fancy code-focused word-processors.

The best answer, to the extent there is one, is to find what works best for your team and code. What’s best for a large framework meant to last decades and be used by half the world will not likely be the exact same thing as what’s best for a tiny bit of Javascript you’re writing to quickly pull some data out of a single HTML document and then will never touch again. It about the trade-offs. Consider questions like:

  • How frequently will this code need to be read, changed, and understood? And by people who aren’t its original author?
  • What tools are the people who modify this code likely to use? How much external documentation will they have access to, and how accessible will it be to them?
  • How much will the other users of this code, and the community of the language it’s written in, be conversant in the naming style you’re using? (Hungarian notation has perks, but only when used where others touching your code don’t just wonder why all those weird letters are at the start of the variable names.)

It’s only by considering issues and questions like those that you can answer the question of what way of naming is best. Where your names should fall on the continuum from brief to explicit is always a judgement call. Focus on what makes sense in your context, and your answer will be better than any outsider will likely understand.

Image Credits: Quinn Dombrowski

Enjoyed that? Join the Press Up newsletter to get our content in your inbox!

13 thoughts on “When Programming, You Must Name Things

  1. Rudy Barbieri

    Typing efficiency???? Many IDE suggest you the name afeter you type 1 or 2 character. In addition you normally copy and paste the function name in order to avoid typing error.
    This means that the only goal when you select a name is to understand how to use it when you read code.

    Reply
    1. David Hayes Post author

      Not sure if you didn’t read carefully or I didn’t communicate clearly, but I mentioned that.

      Not everyone who ever touches your code will have an IDE. While in some teams and contexts, that can be taken for granted, it can’t ever be entirely discounted that someone will be editing with Microsoft Notepad or Unix nano, etc. In that context, it does matter for them in that context.

      Reply
  2. Alan Witmer

    To me, the real God-send for many modern languages is namespacing or packages. One can put a lot of specialization into the class or function and the name space / package can tell it all (or most of it). You still find groups getting into fights over where and how it’s ok to use a “using namespace” clause to simplify the names later in the code, but at least the name CAN be shortened or not, without going redefining the function signature and rippling the change forward!

    Reply
    1. David Hayes Post author

      Good point, Alan. I have to admit that namespacing didn’t even occur to me to mention, but it is a very relevant topic.

      Reply
  3. Michael Main

    One thing I believe about naming (mainly in OO languages), is not to repeat yourself. For example, if a class is named Person and I have a function in Person that moves the Person to a specified position, I wouldn’t call it “movePerson(…)”, I would just name it “move(…)” or “moveTo(…)”. Yet I see a lot of people still doing this. The way I look at OOP is that the code should almost read like a spoken language. You should be able to tell a story with your code. And person.movePerson(…) just sounds unnatural, unless the function caused this person object to move another person object.

    Reply
    1. David Hayes Post author

      That’s a great point that I should have included. Some a your verboseness is handled by the containment of objects. They’ll save you a lot of repetition used well.

      My folder-zipper example could be simplified a lot name-wise if encapsulated in an object that had a method like `recursivelyAddFolderContents()`. Then you get the expressiveness nearly completely, but without at least some of the overhead that was necessary when we weren’t even sure we were trying to create a Zip file.

      Reply
  4. Andre P.

    The two hardest problems in computer science are cache invalidation, naming things, and off-by-one errors.

    Unless you’re absolutely *sure* it’s throwaway code, you should always assume someone else will have to maintain it. A too-long name is a sign that your object hierarchy is too sparse, or not abstracted enough; though, in your example, the contrived extra-long name suffers from other problems. I wouldn’t call your function addFolderContentsRecursively() because it’s 1) redundant: you don’t need “Contents” because there’s nothing else you could possibly add from a folder to a ZIP file, and 2) recursion should be an option parameter. So addFolder() would be a better choice.

    Naming is a particular pet peeve of mine. Too often I see names that don’t match usage, or are misspelled, or ambiguously abbreviated. If you saw a method named getUserAuth(), would you inherently know if it dealt with authentication, authorization, or both? I’ve seen a property whose name began with “Is” but its return value was an integer, not a Boolean as you’d expect.

    Reply
    1. David Hayes Post author

      Good points on all, Andre. I think the broader point you’re making, which I totally agree with, is that naming things is hard and at least a little bit subjective. On your Auth example, I personally have never really gotten the full nuance of authentication vs authorization, and the two concepts are similar enough to me I could see fuzzing over the difference. But to you, they’re very distinct and that distinction is really important.

      All these conversations are making me think that maybe nothing should ever be named — and so practically almost no code should ever be committed — without a second set of eyes on it. Unless you’re the only developer that will ever touch the code, the difference in perspective in understanding the relevant terms is likely large enough to merit the second set of eyes. I know that sometimes the pair will be lazy and let a bad name happen, or a code reviewer will be time crunched and pretend to have considered what they’re looking at before they just hit “Approve”, but adding that filter seems almost certain to increase the probability that a bad name is caught before it’s used throughout a code base and more involved to change. (Although, I do see why someone’s response to this whole idea would be “I hate bureaucratic garbage procedures like that so much…”)

      Reply
  5. Pingback: Why You Should Write Meaningful WordPress Meta Keys | WPShout.com

  6. Pingback: Programming is Storytelling - Press Up

  7. Pingback: Programming is About People - Press Up

  8. Pingback: WordPress Basics: Understanding And Making the Best Use of Your functions.php File | WPShout.com

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>