Code Naming Tips

Photo: Patrick Tomasso - Unsplash

Code style is like fashion style. It is very opinionated and covers a spectrum of good to bad taste with ease. Ask 10 developers how to name things in code and you will likely get 30 answers.

The main thing to remember, as I often state here, is that you will read code many more times than you write it. So, it figures that if you use well defined and clear names in your code it will make it easier when you come back and read it.

Below are a handful of suggestions that I try to adhere to in my own code and which I guide my team to. I do not suggest this is the perfect approach but I have adjusted it over the years through many projects.

1 - If your language has namespaces, use them to segment your code.

An odd opinion to share first but let me explain. Your variable and object names should be short and descriptive. What they should not do is repeat the namespace. Nor should they be tied to a feature by name or be used to group related objects. I have seen namespaces ignored many times in projects which leads to code like

namespace Foo
{
    public class FooReader{  }
    public class FooParser{  } 
    public class FooCalculatorService{  } 
    public class FooDatabaseService{  }  
}

There is no benefit to prefixing Foo to each class name. Use the namespace functionality of your language to segment and organise your objects.

2 - Names should be as descriptive and short as possible.

A bit of an oxymoron there but bear with me!

var o = new NamespaceFeatureFunctionPattern();

// lots of code

if(o.SomeProperty == true)
{
    // do something
}

So a variety of the above code is very common. Short variable names and abbreviations were very common back before I started. A raft of reasons including memory and screen real estate caused their use. But, this is 2017 and I am typing this on a Full HD screen with 32gb of RAM. So those reasons are no longer valid (in most cases). The trouble with very short or abbreviated names is that it makes reading the code really hard. If you use lots of o, a, j, i type variable names then very soon you won’t be able to determine which relates to what type. There are times that short and abbreviated names make complete sense such as counters in loops or indexes.

At the other end of the spectrum is the really, really, long variable names. I worked with a dev once that was so descriptive you would have to scroll to read the whole variable name. I am not joking! This is only just as bad as short names as it makes the code hard to follow and format. Although you do know what the variable relates to.

So how can we improve the code above? First, we need a short and descriptive name for o. We also need to name our object better.

using Myproject.Facades;
var gcalFacade = new GmailCalendarFacade();

// lots of code

if(gcalFacade.SomeProperty == true)
{
   // do something
}

As per point 1, do not include the namespace in your names. I have added a using directive in the code above. Then I have named the object GmailCalendarFacade. It is clear what the object is and indicates any pattern it is based on. The variable is then a shortened name that clearly states what it is referencing. The approach you take can vary based on the items you are referencing together.

3 - Code should read like prose.

Given we read code so much more than write it, it makes sense to make it as easy to read as possible. So, write your code like you would write a story.

A great test for this is to debug some code with a non-developer. Get a business side colleague to sit and run through your code and see if they can follow it. If you have written it clearly enough that they can then you have well named and maintainable code.

4 - It is OK to negate a condition in a name

Some guides you read state that you should not use names such as IsNot or DoesNot. I do not agree and would say you are still aiming for point 3 above.

When did your favourite author last use != in a book?

5 - Use your languages style guide as a guide

All languages have style guides created, usually by the community. Some guides are more strict than others (yes PEP 8 I am talking about you). These guides will offer specific naming and formatting advice for your language. Sometimes a language has more than one community written guides. Pick one, stick to it and remember that consistency is the key. This is especially true in teams.

I have written this based on my experience on many projects built using .Net, Python and Ruby. I am sure that the advice might not carry over to some languages. Functional languages especially put in place different naming conventions. These may recommend shorter more math base naming conventions. The important thing is to ensure your code is clear and concise and following an agreed standard.

If you’d like to discuss my thoughts here then message me via twitter or email.