Clean Names – one of the hard things

Clean names are hard

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

Phil Karlton

Today we are talking about the second of the hard things, luckily this is the one you can keep on improving with ease. I’ll summarize the most important rules you should follow and in future posts we can expand on them.

If there is one thing that you have to keep in mind is: naming is Hard but names are also flexible, if you pick a name and later on find a better one, change it! It will improve your understanding of the software next time you read that file. This flexibility isn’t an excuse to pick a terrible name right now (since you can change it later). No! You must think hard about the names you choose, but also you must change that name if later on you think of a better one.

Use your IDE tools to rename your code, it’s just a quick shortcut away and it won’t forget to change a reference in another part of your project.

Rules

First of all use meaningful names. Names that explain what that object is or does as much as possible.

Date d; //doesn't mean anything
Date date; //it's just repetition
Date lastModified; //This is something useful

The problem with meaningful names is that they are so useful that you start to relay on them (ok that’s not the problem). The real problem happens when you start finding names that look meaningful but actually are a bit of disinformation. What would happen if the requirements change and the variable lastModified now contains the date when a user last read a file? Well, now that name is a lie and it should be changed as soon as possible.

Another possible problem occurs when you use a name that can have different meanings in different contexts, or if you keep referring to the same concept with different words.

Part of what makes naming hard is that sometimes you want to reuse a name but you can’t because the compiler won’t let you. Many times this is actually a problem with the size of your function/classes, if you split a function in smaller ones its local variables are isolated from each other and you can reuse a name (when it’s the most meaningful name to use). Other times novice programmer will try to fix this by changing the names in ways that simply add noise to your programs. The compiler won’t complain but your fellow programmers should.

Check the following two functions

function TransferMoney(int id1, int id2){
var customer1 = GetCustomer(id1);
var customer2 = GetCustomer(id2);
TransferMoney(customer1,customer2);
}
function TransferMoney(int receiverId, int senderId){
var receiver = GetCustomer(receiverId);
var sender = GetCustomer(senderId);
TransferMoney(receiver, sender);
}

Say what you want but in the second one is way clearer whose sending money to whom, and that’s in a 3 line function. How many functions do you have that have way more than 3 lines?

Names should be words you can pronounce. It’s quite common to talk about a pice of code with another programmer, and if you have to spell out loud or you sound stupid saying the name of a variable, that name is hindering your communication. A few abbreviations are acceptable, but you need to keep in mind that it has to be easy to pronounce the names. This rule also excludes most of the encodings (hungarian notation I’m looking at you). In a modern IDE encodings have no place to stay, let your tools gather for you the information about types and access and keep your names simple. No need to burden your mind with this kind of information when your computer can do a better job at it.

Good names are also searchable and that helps you navigate your code and find what you are looking for. In this regard, is quite useful to give a name to magic numbers. If you have to find where you used a variable named weekDays is quite easy. Finding the right instance of the number 5 is a lot harder.

Programmers like sometimes to make inside jokes when naming functions like Apocalypse() instead of a simple DeleteAll(). While this might be fun it isn’t professional and makes life harder to your fellow programmers so no funny names.

Choose names familiar to other programmers (list, visitor, queue) and from the problem domain. Whenever is possible is best to use the same language that your customer uses, that saves you the trouble to keep translating from one language to another.

And lastly: don’t prefix all your names with your project name or an abbreviation. Adding the same prefix everywhere doesn’t add any meaningful information and hinders your ability to work. This is known as smurf naming convention and you should look up its definition.

If you have ever SPWorked on a SharePoint SPSolution there’s no SPNeed to reiterate this SPPoint.

Author: Maurizio Pozzobon

Maurizio has 5+ years developing solutions in the insurance industry. He is passionate about doing the right thing right, so he works in a tight loop with his clients to deliver the best solution possible.

  • Pingback: Stop writing legacy Code – What’s Clean Code – Code cleaners()

  • Mat

    Hey!
    Love the article! 🙂
    But I do have a question: in plain C code you don’t have classes to understand where a particular function comes from when you import a library. I think that name prefixes may be useful in this particular case so a library user knows he/she’s actually using a library function. I’m thinking about the SQLite API, for example: https://www.sqlite.org/c3ref/funclist.html
    What’s your opinion about that?

    • Hi Mat,
      Thanks for your question.
      In my opinion the case you bring to the table is a perfect exception to the rule because, when used like that, prefixes are actually useful. I’m not a C expert but as far as I know, C doesn’t have the concept of namespaces or packages which are very useful to group functionality together, so programmers have come up with the convention of embedding the namespace in the actual name of the function, effectively improving the language.
      This is different from, say, Microsoft.SharePoint.SPWeb because SPWeb is already in the namespace Microsoft.SharePoint and so that ‘SP’ prefix doesn’t bring any important information with it.

      • Mat

        Awesome, thank you very much!