Almost all programmers seem to have their own private naming conventions. Sometimes these just involve the use of upper case letters. Sometimes they are designed to give information that is otherwise hard to find. For example, I used to put a suffix on subprogram or variable names to identify which module they came from. This was when I was programming in C and placed each module in its own file. Finding which file contained a particular subprogram or variable was difficult before I adopted the convention. Now, with things like Ada packages and C++ classes that convention isn't nearly as helpful. My most recent convention serves a different purpose.
As soon as programmer B starts working with programmer A's code, a private naming convention becomes public. Public conventions can be pluralistic or mandated . With pluralistic naming conventions, programmers choose their own conventions but they need to be able to read each other's. With a mandated naming convention, programmers are told by management they must follow a particular convention.
Whether private, pluralistic, or mandated, a naming convention should seldom be elaborate.
When a single programmer's convention is elaborate, the programmer is saying to others "you have a learning curve ahead of you if you want to mess with my code." Few of us wish to project this message -- even with our private code. None of us should project this message when writing code for an organization that permits pluralistic naming conventions.
How about mandated naming conventions? When there is only one convention for all programmers to learn, isn't the learning curve less of a problem? Wouldn't an elaborate naming convention be worth the effort when the result is code more easily understood by coworkers?
Yes, the learning curve is less of a problem and, yes, a single, universally applicable convention that makes code more easily understood by coworkers would be worth a major effort. But
So, don't adopt an elaborate convention for yourself and if you are thinking of mandating one, think again. A simpler convention that you can get consensus on may serve you much better.
Also, don't believe statements like "You always benefit from having some kind of naming convention" which is a "key point" on page 197 of Code Complete.
For an example of an overly elaborate convention, you can, I think, do no better than look at the Hungarian naming convention that appears a few pages later in the same book.
The book actually has lots tips about naming conventions. Do look there for ideas. Another place to look is section 6.2 of Rapid System Development. However, finding ideas is, perhaps, the lessor of your difficulties. The greater difficulty is deciding what naming convention to adopt.
I suggest these criteria
Notice that these criteria are applicable whether you are developing a pluralistic or a mandated naming convention. You can probably find a way to apply them for a private naming convention as well.
I have given reasons why your convention should be simple for you and for your coworkers to understand. Criterion 1 above hasn't been discussed yet. It has two parts. The first of these, that a convention should provide useful information, is obvious.
The second part is that a convention ought not provide information you can get by simply reading the code. Of course, I don't mean information you must study all the code to acquire. I mean information that is readily apparent from a local context isn't very important to reinforce with a convention.
For example, in most programming languages, distinguishing between a variable and a subprogram is easy -- you don't need a convention for it. In fact, you can almost always tell the syntactic category of an identifier from any context in which it is used.
Here's a similar example from natural language. I have a German translation of Isaac Asimov's Foundation series. In that translation all the nouns are capitalized. What useful information do I get from that? My German isn't fluent but it is good enough to recognize a noun without any additional aid. Such an aid is also missing in today's English. Many of us think capitalizing nouns makes a language harder to read, not easier.
Here's another programming example: With my programming style, a convention that identifies loop-control variables would be useless. I keep my loops short by writing procedures when necessary. You can see the whole loop locally. You know what the control variable is.
Put your naming energy into helping the reader find out things that would otherwise be quite obscure.
Here are three sample conventions. Two of them are conventions I currently use. I'm not proselytizing for them. They are just examples of what kind of thinking can go into choosing a convention. They also demonstrate that even for my own simple needs, one convention just isn't enough.
Sample Convention: Constant, Variable, and Procedure Names
Moreover, if a variable is set once during program initialization and never changed, I consider it to be a constant whether the programming language does nor not.
My current way of naming constants can almost be understood from two examples PI and INTEREST_RATE . Constants are all upper case letters and have more than one letter. Variables on the other hand are not all upper case letters unless they have just one letter. Variables do begin with an upper case letter.
I find it valuable to distinguish functions that have no side effects from all other forms of subprograms. Languages provide some support for this, but again this support appears at the place you declare the function -- not the place you use it. I want to know when I see a function invocation that there are no side effects. (By the way, like many people, I consider changing the value of a parameter to be a side effect.)
I name functions without side effects the exact same way I name variables. All other subprograms begin with small letters.
An added advantage of this naming convention is that I can change a variable to a function without having to look for a new name. Here I am not making a distinction that some programming languages don't make either. For example,
OriginalCur := ModuleName.Curmight have a variable or a function on the right. This is a distinction I don't want to make as I will often export a value from a module either way and switch from one way to the other because of an optimization.
These conventions are new to me. I have only recently clarified what I want them for. That's why some earlier examples in this series don't follow them.
This document is written in a markup language called HTML. There, are references to two books in it. Each reference is a hyperlink to a particular part in another HTML file. That part is identified with an anchor which must have a name. What I want is to be able to look at the book itself and figure out the name of the anchor for that book. If I do this at two different times on two different days, I want to come up with the same name -- most of the time. For that I need a convention.
My convention for naming anchors is to append the last two digits of the copyright year to the last name of the first author with all letters lower case. It's not foolproof but it has served so far. If I wish to quote multiple books written by one author in one year, I'll start appending the letters of the alphabet, 'b','c',... This will keep my anchor names unique. Sometimes, but not often, it will make it impossible to look at a book and know what its anchor name is. I accept a little uncertainty in order to keep my convention simple.
Class hierarchies for windowing systems tend to be somewhat complicated. One way to deal with these complications is with a naming convention. (For many programmers, visual programming methods offer a better way but that's off the current topic.)
Borland's ObjectWindows 2.0 can be used as a quick example. There a convention is used that lets you know five different data type names once you know one window class name. For example, if you know there is a class named TWindow, you also know there will be associated data types PTWindow, RTWindow, RPTWindow, PCTwindow, and RCTWindow. These data types give you ways of refering to objects of type TWindow. The choices involve such things as direct referral, indirect referral through a pointer, and the possibility that the object is a constant.
The details don't matter here. What is important is the observation that a naming convention can reflect patterns that are duplicated in a complex system. This makes the system easier to comprehend.
By now, you probably know that I see real value in some naming conventions, that I advocate a few simple conventions with targeted goals over one elaborate convention with general goals, and that I believe imposing a naming convention without consent of the people who must use it is a mistake. Copyright and Permissions
This tip is distributed to individuals free of charge from the Software Build and Fix web site. All other distribution (including but not limited to internal distribution within an organization and mirroring of any kind) is forbidden without written consent of the copyright holder.
Return to the top of this document.