Best Practices – Naming Standards Part One

Best Practise

One of the most important parts of writing good code, be it in a test, framework or anywhere else, is that it’s readable. One way to achieve this is to make sure that you stick to good naming standards within your code. This applies to everything from variables, methods, tests and classes.

Back when I first began coding and would write hobbyist projects, I would code with the assumption that it would only ever be me reading the code, so only I had to understand it. Which is all well and good until you have been away from that code for a while and go back to it, realising that you now can’t remember what it is that your ambiguously named variable is used for, or how your utility methods all without clear names don’t really make sense at first glance. It made working on old code really painful and slow, having to spend ages just working out what I was trying to achieve rather than actually coding.

These problems become even more painful when working within a team or company that has multiple people working on the same codebase. Everyone working with their own naming standards and just calling stuff what they want will eventually lead to catastrophe in the long term, but short term, it makes for some really frustrating peer reviews for all involved.

Let me show you and example of what I mean.

public void Main()
{
    var a = 4;
    MyMethodForNumbers(a);
    Console.WriteLine(a)
}

Imagine your method MyMethodForNumbers was stored elsewhere, and running the above code via a console application and you were presented with an output of 16. I’m sure if you thought about it enough, you could work out that it’s a number squared method, or is it? How could you know for sure or have any confidence using that method. For all you know that method always returns 16 no matter what is passed in. Also, our variable name. What does ‘a’ mean? In the above it’s probably not too much of a problem, but if that was a property for a class or a method to be used across a number of operations, how would we have any idea what it’s intended purpose should be.

public void Main()
{
    var numberToBeSquared = 4;
    SquareMyNumber(numberToBeSquared);
    Console.WriteLine(numberToBeSquared)
}

Straight away that makes more sense, we can see what it is we intend to do with our variable as we understand exactly what our method does because of its clear naming.

This example is obviously extremely basic and written to highlight a point, that if with three lines of code we can cause confusion with poor naming, imagine what we can do with hundreds or even thousands of lines of code with no set naming standards.

So what exactly is good naming? Well let’s start with variables

// Good Variable Names
int numberOne = 1;
string name = "Toby";
bool isNumberEven = false;
int counter = 0;
string[] arrayOfNames = ["Tim", "Toby", "Tom"];
bool isFileSaved = true;

// Bad Variable Names
int number = 0;
string someone = "Toby";
bool yesorno = true;
string[] words = ["Bad", "Poor", "Awful"];
string strN = "Joe";
string house = "1 Test Lane, Testville, TE57 1GQ"

As you can see above, the good names describe exactly what they are and the data they contain. There’s no ambiguity as just by looking at the name, you could tell what they are. And more importantly, I could remove the implicit declaration and you’d still be able to know what kind of variable it is, whether it’s an int, a string or so on.

The bad variables are the complete opposite. The first integer called “number”, yes we can tell its a number but a number used for what? Where it will be used. The other variable names in that list are as bad, giving no clear indication as to their content or the intended use. These would also make less sense if they weren’t implicitly declared.

What about method names? Let’s have a look at some good and bad ones.

// Good Method Names
FindEmployee();
CreateAccount();
ReturnSquareRoot();
FindEmployeeByName();

// Bad Method Names
MyMethod();
HandleData();
TempMethod();
StringChecker();

Like the variables examples, looking at the two lists, it would be clear without the comments which are good and bad. The good clearly describe exactly what they are doing, and how they are doing it whereas the bad names give no idea what it is they are doing. StringChecker for example, you might argue that it’s good as it clearly states it’s checking strings. Checking for what though?

It’s not just about being clear as to the variable or methods purpose though. You also have to make sure that they adhere to basic coding guidelines. Using PascalCase or camelCase in naming is important depending on what it is you’re naming. If you haven’t heard of those terms before, here is a quick definition of both:

Pascal Case: This means that the first letter of every word in the name is capitalized. In Pascal Case, if an acronym exists in the word then only the first letter of that acronym should be capital. Eg: ThisWordIsInPascalCase

Camel Case: It is the same as Pascal Case, but the first letter of the first word is lowercased. Eg: thisWordIsInCamelCase

Understanding when to use which can be difficult, especially if you’re fairly new to coding. So I’ve included the following table to give a better idea. It also contains useful rules about other areas of naming, such as length, use of abbreviations and underscores.

Object Name Notation Length Plural Prefix Suffix Abbreviation Char Mask Underscores
Class name PascalCase 128 No No Yes No [A-z][0-9] No
Constructor name PascalCase 128 No No Yes No [A-z][0-9] No
Method name PascalCase 128 Yes No No No [A-z][0-9] No
Method arguments camelCase 128 Yes No No Yes [A-z][0-9] No
Local variables camelCase 50 Yes No No Yes [A-z][0-9] No
Constants name PascalCase 50 No No No No [A-z][0-9] No
Field name camelCase 50 Yes No No Yes [A-z][0-9] Yes
Properties name PascalCase 50 Yes No No Yes [A-z][0-9] No
Delegate name PascalCase 128 No No Yes Yes [A-z] No
Enum type name PascalCase 128 Yes No No No [A-z] No

Now you understand the basics behind naming. In part two, we’re going to go in to more detail about methods and the extra rules about those. Things like parameter naming, number of parameters and a method having more than one purpose will all be covered.