Naming items

Martin McBride, 2017-03-21
Tags none
Categories none

When you write code, you will spend a lot of time thinking up names for things. Variables and functions, then as you write bigger programs you might also be creating classes and modules.

There are some people who even say that programming is mainly about thinking up names for things! That might be a bit extreme, but it is very important to give items good names, because the names you use can have a huge effect on the readability of your code. And more readable code is more maintainable code.

Naming styles

Simple function or variable names might be just one word, such as "print" or "input", but often you need more than one word. For example if you have a program that calculates a value, then the function that prints the result should be called something like "print result".

Unfortunately, that isn't a valid variable name in most languages, because it includes a space. There are 3 main alternatives:

  • PrintResult - this style is sometimes called camel case because the capital letters are like the humps on a camel's back.
  • print_result - this style is sometimes called snake case.
  • printresult - this style isn't used as often, because it is harder to read and can sometimes be ambiguous. It works in cases where two words could be joined to form a composite word, for example filename. Generally it is best avoided.

Java and C# typically use camel case, Python typically uses snake case, some other languages are a bit less clear cut. Whichever you use, it is best to choose one style and stick to it.

Good names

When you are writing code, it is worth remembering: you write code for humans to understand.

Of course, the interpreter or compiler must "understand" your code too, but it doesn't care what you call your variables. Always think of the poor human who might have to read it.

The general rule is to make names descriptive

Naming conventions

Some languages have naming conventions that most programmers use. It is a good idea to follow these as it makes you code more readable for other programmers. Here are some common ones of ten used in Python, Java, C and other languages:

  • Variable names usually start with a lower case letter, such as count or name.
  • Function names usually start with an upper case letter, such as RequestUserName or ConvertInchesToMM.
  • Constant names are usually all capitals, such as PI or MAX_NUMBER_OF_COLUMNS. They usually use snake case (underscores) even if the rest of the code uses camel case (because camel case doesn't work with all caps).

Also, variable names are often nouns because they represent things in your program, but function names are often verbs because they represent actions in your program.

If you program using classes:

  • Class names also usually start with an upper case letter, such as StudentDetails, and are usually nouns.
  • Class methods usually start with a lower case letter, and are usually verbs.

Things to avoid

Here are a few things you should usually avoid:

  • Don't abbreviate names, for example stdnt_nm isn't a good variable name, call it student_name instead.
  • Don't use really long names, that can make your code hard to read too, especially if it overflows the screen or paper. You shouldn't usually need more than 10 to 15 characters for a name.
  • Don't use single character variable names (but see below).

Try not to include pointless information in your names:

  • xyz_variable or xyz_value - we already know it is a variable and that it contains a value, no need to include it in the name.
  • myXYZ - just looks a bit silly.
  • xyzString - it isn't usually necessary to include the data type in the name. Also, if you ever change the data type you either need to go through an change the variable name everywhere, or else you have misleading code

Sometimes you might see, for example, a list of student called studentList. That isn't too bad, but it might be better to just call it students.

Single letter variable names

People may tell you that you should never use single letter variable names, but they have their place:

  • i, j and k can be used as loop variables. It is fairly conventional, everybody knows what it means. Calling your variable index instead of i is fine, but not really necessary.
  • x and y can be used to represent coordinates
  • Short variable names are often used in example code. If the code sample is only 4 lines long and only uses 3 variables, there is nothing wrong with calling those variables a, b and n.

Copyright (c) Axlesoft Ltd 2020