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.

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.

If 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