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

There are only two hard things in Computer Science: cache invalidation and naming things.

— Phil Karlton

ᔥ http://martinfowler.com/bliki/TwoHardThings.html

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)

  1. Acronyms
    1. 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.

  2. Abbreviations or Phonetic Substitutions
    1. This isn’t LOLCODE people, NoAbrvFuncNamsPls KTHXBYE
  3. Hungarian Notation

    Good advice from uncle bob.

    … 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.

  4. and / or / with
    1. 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.
  5. 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.

2 thoughts on “Confessions of a code-reviewer: What’s in a name?

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s