Confessions of a code-reviewer: What’s in a name?

This is an honest plea, free of smugness or sarcasm: Please make your names count. When thinking about what to call something, think about the fact that your code may well outlive you, or at the very least your tenure with your current company, and make it something meaningful enough to stand the test of time. Your fellow developers will thank you, and who knows, you might even find that the life you save is your own. Maybe you aren’t too thrilled with your current team and you’ve decided to take revenge, or your pants don’t fit quite right, or you’ve got a bad marriage, whatever it is that compels you to write a function called fnCalcCurSal just stop; put the keyboard down and read below. Good names improve understanding, and bad names, well, bad names make your code look terrible and people will point and laugh at you. Don’t become an object of ridicule. Rise above, and cast your scorn down upon those who use silly names.

This is a cobbled together list (in no particular order) of official guidance from the Microsoft Framework Design Guidelines and my own personal opinions on what makes a good function name. Feel free to disagree.

Things to absolutely avoid in method names

(things get a bit dicey with variable names because opinions on those are more diverse)

Acronyms

industry standard or otherwise, they really don’t belong in the method name. The most glaring reason for this is that the upper-case characters which make up the acronym break the flow of upper to lower case which makes CamelCase so nicely readable.

ex:

// not a great name
StartCPROnTheTestDummy();

Here we’ve blended the acronym CPR with the first letter of the word On, and hampered readability, even if only slightly.

… nowadays HN and other forms of type encoding are simply impediments. They make it harder to change the name or type of a variable, function, member or class. They make it harder to read the code. And they create the possibility that the encoding system will mislead the reader.
–Robert Martin

And more here from Linus.

Encoding the type of a function into the name (so-called Hungarian notation) is brain damaged—the compiler knows the types anyway and can check those, and it only confuses the programmer.
–Linus Torvalds

Hungarian Notation is a code smell. Forget you ever used it, and never use it again.

and / or / with

If your functions contain these words, you are probably over-describing what the function is doing, rather than how it should be used, or the reason it should be called.

Implementation specifics

I haven’t seen this in any publications, at least none that leap to mind, I’m just offering it as good advice if you want your code to remain self-documenting. If your function advertises itself as having certain behavior, and the underlying implementation changes, then the name of the function should change to remain consistent. Knowing this, avoid leaking information which the caller has no business knowing. Encapsulate your ideas and name your functions with a little detail about behavior, but mostly think about the reason someone might call your method, not exactly what it does.

For instance, you wouldn’t want to choose a name like GetDataFromSqlServer because this includes information that the caller really shouldn’t be privy to. He shouldn’t care where you got the data from. If sometime later you decide to change the source of the data, this method (and all calls to it) would need to be changed. The inverse is almost worse in a way. If the implementation strategy changed but the callers still believed they were getting data from SQL Server that might also be bad. Again, consider why not how.

As programmers, we owe it to ourselves and our fellow geeks to write good code; code we can be proud of. I hope this list has been helpful, and if you have any additional tips I may have missed feel free to comment below.