Practical .NET

Creating Useful Naming Conventions: Business Considerations

Peter continues to look at the value of imposing naming conventions on developers; but this time, he looks at the benefits related to understanding the business problem, as well as why flexibility is crucial.

• By Peter Vogel
• 12/20/2013

In an earlier column ("Creating Useful Naming Conventions: Technical Considerations"), I looked at the benefits that naming conventions have historically provided to individual developers in preventing programming errors. I suggested that, with the exception of distinguishing between parameters/fields/local variables, most of those issues were now handled by the tools we use (i.e., Visual Studio and IntelliSense). But in that column, I also suggested that a different set of benefits were related to understanding the business and in reading (rather than writing) code. That's what this column is about.

To begin with, all coding conventions, including naming conventions, have value in standardizing code across a shop. Programming is still a craft and, as a result, every programmer's code looks different. A set of coding conventions helps to standardize programmers' output around the things that don't matter, reducing the differences to the things that do matter -- what's special about the problem this code solves.

Defining Meaningful Names
Naming conventions have specific value in helping the reader understand the problem that the code solves, provided that the names you give relate to the problem. This goes back, of course, to the old advice about assigning "meaningful names" to the components of a program. Unfortunately, one person's "meaningful" is another person's "Wha...?"

The best names for variables, methods and properties draw from the problem space and, especially, from the business-related problem space. The best names help the reader understand what the code is doing about the business' problem. This means that a method name like IncrementCounter isn't very helpful: It reflects what the computer is doing, not what contribution this method makes to solving the business problem. Besides, you could figure that out by reading the code. A better name might be AddACustomer, for instance.

But unless you're willing to come up with names for every business entity that you might have to write code around, it may appear that there's no rule to be applied here other than "Pick your names from the business space." There are, however, two additional guidelines that you can follow.

Drawing names from the business or problem space can result in long names that are going to be difficult for readers to process. The first guideline, therefore, is to put what's different about the name at the front of the name. If you have two classes that support two different kinds of customers, it may be tempting to name them CustomerPremium and CustomerDeadbeat. That emphasizes their similarity, but it also means that a developer reading your code has to read to the end of the name to find out which kind of customer the code is working with. You'll be better off putting the distinguishing characteristic at the front of the name: PremiumCustomer and DeadbeatCustomer. The latest versions of IntelliSense will let you search for every class that contains the word "Customer," so you'll still be able to find all of your Customer classes when writing code.

The second exception is around abbreviations. If some terms (like Customer) crop up frequently enough in your shop, it can be worthwhile to establish what abbreviations your shop will use consistently. This not only shortens the names but, since distinctive terms aren't common and won't be abbreviated, it also highlights the infrequently used terms in the resulting names. Following this guideline, PremiumCustomer and DeadbeatCustomer become PremiumCust and DeadbeatCust, for instance, giving prominence to what's special about these classes.

Ignoring the Conventions
While the costs of imposing a naming convention are low, the benefits of having a naming convention may be lower -- perhaps even zero. They're certainly difficult to quantify, other than with a gut feeling that they are a "good thing." Conventions shouldn't be forced onto every item in a program. Where an item is computer-related (rather than business-related) and is highly localized, the value of a naming convention is probably zero (and, if you factor in the cost of applying the rule, perhaps negative).

When I declare a class that I'm going to use and discard in five lines of code, I don't worry about naming conventions. If I need to retrieve information about a file, I'll use .NET's FileInfo object. There's very little business "meaning" to this class; it's just the class I have to use to get the information I need. That means that if I'm using the object in code that will fit on one screen (i.e., in less than 20 lines of code), I'll declare it like this:

Dim fi As New FileInfo(CustomerAccountFileName)

If the reader isn't sure what "fi" is when it appears later in the code, clicking on the variable will highlight all of the places where the variable is used, including its declaration slightly farther up on the screen. That declaration includes information about what file I'm retrieving information about.

This isn't going to work, however, if the declaration is widely separated from its use (i.e., more than 20 lines). In that case, I'll rename the variable to include information about the contribution that the item is making to the business problem by rolling in the file name:

Dim CustAcctFileInfo As New FileInfo(CustomerAccountFileName)

I would also do this if I had two FileInfo objects that I was using simultaneously.

Farsighted readers will suggest that it's possible that, in rewriting the code, my variable declaration will move far enough away from its use that I would feel that a meaningful name is justified. And if that happens, I'll change my convenient short name to the more meaningful longer name. Visual Studio will then ripple the change through my code for me.

Having an invariant rule is almost always a bad thing. The conventions you want to impose on your developers should, like a good menu, be context-sensitive. And part of that context is recognizing what your tools will do for you and doing only what you have to in order to compensate for those tools' deficiencies.