Robert’s Rules of Coders: #3 Use Good, Meaningful Names

Code is much easier for humans to read when the variable and function names reflect what they mean and do. In ancient times, like the 1960s, some programming languages did not support long variable names, but today almost every language supports long names with no penalties. Although some exceptions may be tolerated for very common usages such as the variables “I”, “j”, and “k” for loops, you should strive to use meaningful names in all cases. Would anyone honestly say that the first block of code below is easier to understand than the second?

Good, meaningful names not only make your code more readable, but they may also remove the need for you to add comments or documentation to the code.

When we first began writing JavaScript in the 1990s, we used short variable names because we wanted to reduce the size of the files to make them faster. Today, you should probably not do this because the data is compressed by default by technologies like gzip, and Internet speeds are faster, and if you are writing enough code that the size of your JavaScript is a factor you should be using a minifier tool to make the JavaScript smaller for you.

Aside from long names, what makes a variable or function name good?

• Good names reflect the value stored in the variable or explain what the function does. “Counter1″ is better than “c”, but “ActionCounter” is even better. Giving variables relevant names reduces the time it takes people in the future looking at the code to figure out what it does. And that includes the future you. This applies to function names also. A function named “UpdateActivityCount” is better than “CountUpdater”.
• Try not to use negative logic in variable and function names. It takes our brains a little longer to deduce the meaning of negative logic statements.
  • IsValid is usually a better name than IsNotValid
  • DoesValueExceedMaximum is usually better than DoesValueNotExceedMaximum
• Follow the conventions of the language you are coding in. If the language uses CamelCase, you should use CamelCase. If the language uses Hungarian Notation (txtFirstName, intItemCount), you should use Hungarian notation. If the language uses all upper case for the names of CONSTANTS, you should use all upper case for CONSTANTS too.
  • In JavaScript, most variables and functions start with a lower case letter. Global variables should be all caps.
    • Source http://javascript.crockford.com/code.html
  • In C#, do NOT use Hungarian notation. Do not use abbreviations.
    • Source https://msdn.microsoft.com/en-us/library/ms229045
  • In Java, use a lower case first letter and mixed case. Use all upper case for constants.
    • Source http://www.oracle.com/technetwork/java/codeconventions-135099.html
• Don’t reuse variable names for different purposes.

  

  Example of Reusing a Variable
• The function name should describe what it does not how it does it. This allows you to change how the code in the function works without needing to change the function name. This helps the function remain a black box.
  • Name the function GetAllCustomers, not CallDatabaseUsingADOtoGetDataFromCMCUSTTable.
• Avoid names that might match keywords. Naming a variable “Name” or “Date” might compile safely at first, but it might fail after an update to the language is installed, or if you include a new library in the project. Also, it may not be obvious to other developers that the variable name is one that you created instead of one that is built in.
• Follow a consistent pattern
  • If your Foo object has a Retrieve method to get data from the database, then your Bar object should also have a Retrieve method to get data from the database, not a Get method. Using the same method and property names across objects when the methods serve the same functions reduces the learning curve for new developers.
  • You should also strive to use consistent noun and verb pairings. Naming two functions, CalculateLastSaturday and CalculateLastSunday is usually easier for programmers to remember than having one function named CalculateLastSaturday and the other named FigureOutFinalSunday.

Finally, remember to rename your variables if the meaning of the value they store changes and rename your functions if the things the function does changes. We are writing code for humans, not for computers.

Are there any more good rules that should be added to this list?