Best Practice: Naming Conventions

i = 0, j = k + t % rr ok? Do we even know what the heck that is saying? This is the kind of stuff programmers have to deal with when editing someone else’s code. What do these things mean? As programmers we should strive to make code better than we found it. A keyword here is “Naming convention”. We will explore what it means to have one and what good does it do for us…. next on the Programming Underground!

In the book Coding Complete by Steve McConnell, he talks briefly about naming conventions and what they are. It is the process of naming variables, classes, methods and functions in a standard consistent way. One of the more commonly used naming conventions is Hungarian notation where names are specified with the type of object it is and then the name. For instance… if we have an object representing a recordset, the variable may be named rsPatientRecords where the “rs” stands for the type of object, a recordset, and then the name specifying what type of recordset. Other examples include strName for a name string and intRecordTotal for an integer representing the total number of records.

Some programmers like this naming convention and others do not. It is a style issue and while out in the industry you may run into it from time to time. Heck, your company may even enforce this naming convention on all the code you write. By enforcing such a convention, companies can create a more consistent feel and standardization to all code written by the multiple teams. It gets everyone on the same page.

On DIC I spend a great deal of time actually deciphering what the programmer means by declaring a variable. By understanding what is meant by the name, I can then get to the problem and provide a solution. It is a readability factor when other programmers (or even yourself) sees the code later and quickly understand what is being done. Here is a great example…

i = s / 3.0;

To tackle this problem above I have to spend time figuring out what “i” and what “s” represent. Seasoned programmers recognize “i” as short for “index” in a loop and that is usually the first thing that comes to mind, especially when it is in a loop. It may or may not be an index. In our example it isn’t.

Now here is the same example but with a naming convention that makes things more readable…

dblAvg = dblSumOfNumbers / 3.0;

Ahhh we see that we are calculating an average based on the sum of some numbers divided by 3.0. We can even extrapolate that dblSumOfNumbers is the sum of 3 numbers since we are dividing by three. We also know that average is a double and so is the sum of the three numbers.

Now I am not saying Hungarian notation is the “BEST” of naming conventions… there are many more, but it is usually one taught in universities and in some books for beginners. It is usually pretty easy to pick up and use and is understood by a lot of people in the industry.

“So Martyr, what does this do for me as a programmer? I know what those letters meant, I wrote them!” Yeah you may know them now, but are you sure you will know them a few months or over a year from now? Perhaps you have written 100 other programs since this one and in each your variable “s” represented something else in each one of them. Maybe you are not going to be the next person to see this code. Perhaps you moved up in the world and onto another company that pays you a quarter million dollars a year (yeah right!). That programmer will then have to decipher what “s” means and that costs time… time is money! Plus it introduces the possibility of not fully understanding the problem (if your code was perhaps bugged… yeah like that ever happens!) and then the programmer may include an error of his own.

So he main reasons for having a naming convention…

1) Improves readability
2) Reduces the chance that someone makes an error because they don’t fully understand the problem.
3) Reduces development time, costs, and complexity by making it very easy to understand what is going on.
4) Helps in refreshing your memory in the future of what you did and how you did it.

Other Naming conventions include Positional conventions where you summarize large names and sentences into small (typically less than 8 or 9 character) variables. These summarization may include the name of the project, the process, and the sequence like “MarAdd2” representing “Martyr’s application, addition function number 2”.

This entry is not to say one is better than the other but that programmers should do everything in their power to make their code readable and maintainable so that other programmers find it easy to update and modify. If you are unsure your company or class has a naming convention in place, you can ask which to follow or have them create one. As long as the convention is consistent, understood by everyone, and makes things more readable, then the convention is good.

In the long run everyone wins. The employer, you, and the programmers following your legendary DIC coding legacy!


About The Author

Martyr2 is the founder of the Coders Lexicon and author of the new ebooks "The Programmers Idea Book" and "Diagnosing the Problem" . He has been a programmer for over 25 years. He works for a hot application development company in Vancouver Canada which service some of the biggest tech companies in the world. He has won numerous awards for his mentoring in software development and contributes regularly to several communities around the web. He is an expert in numerous languages including .NET, PHP, C/C++, Java and more.