Naming rules

[David Bajgar]

Hi all,
Is somewhere (codeguru, MSDN) a document which describes naming convention for variables, functions, methods, structures, classes in C/C++?
I found only Hungarian Notation article in MSDN.


Thanks in advance for any tips,
David

[Graham]

Herb Sutter has no time for Hungarian Notation: http://www.cuj.com/experts/1911/hyslop.htm

Try this: http://www.objectmentor.com/resource...les/naming.htm

[proxima centaur]

I started off using hungarian notation but decided it was not good practice.

1- When you change the type of a variable, you have to change its name. It's annoying.

2- If you write short enough functions, you can easily see the type of a variable as it is just a few lines away. Thus a prefix is of no real use.

3- As you pointed out, there is no "standard" hungarian notation.

The only prefix I use on my variables is a hefty "m" in front of all my member variables (members of a class). Other than that, I just write the variable in plain english, without any underscore "_".

Of course, this represent my view on the topic, you are entitled to have your own views!

[cup]

The naming rule is whatever you and the people you are working with feel comfortable using. It works for some and doesn't work for others (mainly those who never have to maintain programs). You just have to agree a rule amongst yourselves and stick to it. You will need to watch out for the "not invented here" programmers. They will just wreak havoc with the naming.

Also there is the rule within the rule. eg if pointers begin with p, members of classes begin with m and handles begin with h, then which permutation of p, m, and h would a pointer to a handle which is a class member have? Again, some would say mph, others would say phm.

You may also need a file and class naming convention. For instance, looking for Manager in mgr.cpp, man.cc or mngr.cpp is annoying if you are new to the project. If they named it Manager.cpp, it would be easy to find.

I know this doesn't help a lot but naming is a very personal thing. Some like it and others loathe it (especially if they won't be there to reap the benefits).

[proxima centaur]

Originally posted by cup
...
Also there is the rule within the rule. eg if pointers begin with p, members of classes begin with m and handles begin with h, then which permutation of p, m, and h would a pointer to a handle which is a class member have? Again, some would say mph, others would say phm.
...

This example is part of what I'm talking about. This notation works fine with a very small team of 1 person. With bigger teams, everybody will have their own idea on what the order of the letters in the prefix should be. From experience, if you can't have a consensus on that topic, and it is utopic to think one can be reached, it renders the notation useless as only the person who wrote it can understand what it really means. If you have to go check the variable definition anyway, what's the point?

[Steve Rendell]

You should also be able to tell the type of the member (pointer, reference etc) by it's implementation.

i.e. student->setName("joe") ; indicates that student is a pointer where student.setName("joe"); is a reference...

[TruBic]

I struggled with that question again and again and never satisfy! My point of view is when look at someone code, the first thing we want to know is "How to use this or that", not "What is this or that". So I think the type of a name is not as important as the scope of a name. Look at some name and you can know right away that whether you can use it, ignore it or can use it with some attention that would be great.

Ex: for a class if we can distinguish all public members from protected and private members it should be very good. Or we can tell whether a variable is global, a parameter or just a stack variable...

Anyone suggestion should be great.

[AnthonyMai]

What is wrong with Hungarian Notation? I do not think HN is the best naming convention possible. To those people who criticize HN, fine with me, but please propose your alternative, supposedly better naming convention here. If you have nothing better to offer, then just don't criticize HN.

In any measure, having a naming convention is much better than not having one at all.

I could never understand why people hate HN? Maybe it is part of the Microsoft bashing culture?

I like the idea of using name prefixes to identify the variable data type, like m_ for class member, g_ for global variable, p for pointer, n for unsigned integer, i for signed integer. a for array, r for reference, etc.

1- When you change the type of a variable, you have to change its name. It's annoying.

You positively and definitely need to change the variable name when its type is changed, even if it is not because of naming convension. If a variable type or its usage is changed, chances are it no longer fits in the code where it originally fit. Name change gives you a chance to carefully review every spot the variable occurs, and make sure the code still makes sense.

2- If you write short enough functions, you can easily see the type of a variable as it is just a few lines away. Thus a prefix is of no real use.

How do you know that your function will still stay short after a couple of months and some more changes? How short is short? How long is long? Where do you cut the line? It is better to maintain a consistent naming convention throughout the code set, regardless of the function size.

3- As you pointed out, there is no "standard" hungarian notation.

So since there is no naming convension standard, you propose there should be naming convension to follow and every one just do their own naming and go ahead call their cats donkeys and they dogs monkeys?

[PaulWendt]

Originally posted by AnthonyMai
In any measure, having a naming convention is much better than not having one at all.

This I agree with.

I could never understand why people hate HN? Maybe it is part of the Microsoft bashing culture?

At first glance, it just looks silly. Once you get used to it, you can't
think of variables any other way [I was there, trust me]. I think
people look at it and bash it without giving it a try because it
just plain looks retarded

I like the idea of using name prefixes to identify the variable data type, like m_ for class member, g_ for global variable, p for pointer, n for unsigned integer, i for signed integer. a for array, r for reference, etc.

Will wonders never cease? I actually agree with a lot of this,
myself. I prefer to use m_ for class members, p for pointers and
g_ for global variables. I pretty much draw the line there, though.
My only real naming convention is to use have a capitalized class
name and have a lower-case object name [but each word would
be capitalized]
Example:

ExampleClass exampleObject(someValue, anotherValue);

You can't look at 'someValue' and "anotherValue" and know what
they are there for, but neither are the names descriptive. They
are just examples.

You positively and definitely need to change the variable name when its type is changed, even if it is not because of naming convension. If a variable type or its usage is changed, chances are it no longer fits in the code where it originally fit. Name change gives you a chance to carefully review every spot the variable occurs, and make sure the code still makes sense.

I like how you say "positively and definitely" and then modify that
by saying "chances are". <shrug> Oh well ... details, details.

How do you know that your function will still stay short after a couple of months and some more changes? How short is short? How long is long? Where do you cut the line? It is better to maintain a consistent naming convention throughout the code set, regardless of the function size.

... in my [AnthonyMai] opinion.

So since there is no naming convension standard, you propose there should be naming convension to follow and every one just do their own naming and go ahead call their cats donkeys and they dogs monkeys?

I have to agree with you here, too. There are easy ways to say
that THIS is the one, true Hungarian Notation for THIS develop-
ment group. Whoever draws up the "outline" would specify all of
the pertinent rules.

Frankly, I don't use Hungarian Notation all too often any longer. I
used to use it ALL of the time; I grew accustomed to it and it
finally lost its appeal to me. I selected bits and pieces of it to use.
One rule of thumb I go by though: if you ever have to specify
the variables data-type in its name, then you're better off using
hungarian notation.
Example:

int intValue; // in my opinion, this is a bad name
int nValue; // in my opinion, this is a better name
int iValue; // as an alternate

I think that hungarian notation is so widely-used that the prefixes
are evident to most programmers ... and they do save typing.
I typically won't use any modifier on the name, though:

int queryValue;

That works fine for me

--Paul

[proxima centaur]

If it is not Anthony Mai

Originally posted by AnthonyMai
What is wrong with Hungarian Notation? I do not think HN is the best naming convention possible. To those people who criticize HN, fine with me, but please propose your alternative, supposedly better naming convention here. If you have nothing better to offer, then just don't criticize HN.

Even if I had nothing better to offer, please, leave me my right to criticize!

In any measure, having a naming convention is much better than not having one at all.

True. But it has to serve a purpose. You have to decide why you are using a notation rather than blindly use it under the impression it is the "good" thing to do. Hey! If 1M programmer use it, it must be the way to go. I don't buy it. I used to use HNotation, I changed my mind.

I could never understand why people hate HN? Maybe it is part of the Microsoft bashing culture?

Yes. But that's not because it is MS who initiated this movement with the help of Charles Simonyi a hungarian that *I* bash it. I bash it because I used it for years, then found a new way to program, with more efficiency. I found the use of prefixes obfuscate the code and doesn't really help and in fact keeps my coding pace low as I have to ponder to figure out a prefix to name this particular case for a variable: ex.: pointer to a pointer of char*...

I like the idea of using name prefixes to identify the variable data type, like m_ for class member, g_ for global variable, p for pointer, n for unsigned integer, i for signed integer. a for array, r for reference, etc.

The only prefix I allow in my notation is prefix for scope.

Local scope is simple: no prefix
Member: m (without the annoying underscore)
global: g (never use it anyway)

I don't use other prefixes. for the exact reason offered by cup: How do you represent a pointer to an array of pointers anyway?!?! So much for clarity!

The lack of real standard also amazes me. For an integer, you would use i... but only if it is not an index, where you would use n... and for a string... sz... or s in some companies... Even the MFC code doesn't follow a clear convention! This shows me that "so-called" Hungarian Notation is failing to make the code clearer.

You positively and definitely need to change the variable name when its type is changed, even if it is not because of naming convension. If a variable type or its usage is changed, chances are it no longer fits in the code where it originally fit. Name change gives you a chance to carefully review every spot the variable occurs, and make sure the code still makes sense.

FALSE!

If I change a pointer for a reference or a int to an unsigned int, under my convention, I do not need to rename my variable and do a search and replace to change the occurences. I only need to arrange my code (change * for & and such...).

If I don't need the variable, I delete it. That's it.

How do you know that your function will still stay short after a couple of months and some more changes? How short is short? How long is long? Where do you cut the line? It is better to maintain a consistent naming convention throughout the code set, regardless of the function size.

That is also part of my convention. My function will grow with time. I fix a length I'm comfortable with as my max function length. Right now, it is 40 lines per function. If it grows beyond that,I need to refactor. I split the function in two or more. This is part of my extreme programming discipline.

So since there is no naming convension standard, you propose there should be naming convension to follow and every one just do their own naming and go ahead call their cats donkeys and they dogs monkeys?

No. You call cats Cats, and monkeys Monkeys. And you know what? It's simpler, and easier to maintain. And that's my goal. I do not need cosmetic prefixes. The type of my variable is clearly stated out at the place where it is declared, therefore I have all the information I need to program.

Here is an example of how I code. This might look to you as a lack of convention but for me, it is enough:

/**
 * Returns whether or not the file exists.
 *
 * @return true if the file exists.
 */
bool
	CFileName::Exists() const
{
	bool Result = false;

	const string Name = FullName();

	if ( Name.size() > 0 )
	{
		FILE * Handle = fopen( Name.c_str(), "r" );

		if ( Handle != NULL )
		{
			fclose( Handle );
			Result = true;
		}
	}

	return Result;
}

This is my proposal. And it works. Everybody at work uses it and our productivity hasn't suffered from it.

My point is: do what you want, do what works for you.

If Hungarian Notation is making you comfortable, by all means, use it. I personally find it is a waste of time.

[proxima centaur]

Originally posted by PaulWendt
Frankly, I don't use Hungarian Notation all too often any longer. I
used to use it ALL of the time; I grew accustomed to it and it
finally lost its appeal to me. I selected bits and pieces of it to use.
One rule of thumb I go by though: if you ever have to specify
the variables data-type in its name, then you're better off using
hungarian notation.
Example:

int intValue; // in my opinion, this is a bad name
int nValue; // in my opinion, this is a better name
int iValue; // as an alternate

int Value; // seems the best to me, although Value doesn't really means anything out of context...
// A less general identifier would be better!

I think that hungarian notation is so widely-used that the prefixes
are evident to most programmers ... and they do save typing.

I totally disagree, and I think this is exactly the assumption everybody does and shouldn't. We all don't think alike!

What do you use as a prefix for a string? I've seen sz and I've seen plain s. To most of my colleagues coming from a Visual Basic background, s was the way to go, whereas for fellow C programmers, sz was unquestionable. Then, there was me, I chose s because it was 1 letter less to type

As I also pointed out, even Microsoft programmers don't all use the same notation for the same variable types.

That works fine for me

--Paul

That's all that counts if you work alone.
If it works for others who will use your code, it's better

[Yves M]

Interesting topic.

I'm somewhere in-between hungarian notation and custom adaptation. I do use the g_ (global) , m_ (member) and p (pointer). I'm not sure if this is Hungarian notation, but I also use b for Boolean values. s is reserved for structure types, the ugly prefix "bstr" is what I actually use for BSTRs... Oh well...

But you won't see me prefix any DWORDs with dw, ints with int or these things. Most of the time they are not really relevant.

I read that Herb Sutter link by Graham and it does make sense to me that in the days of OOP you should not have to use these prefixes anymore.

I mean the point of all of this is that you make your code readable to yourself and a third party (your collegues maybe), so it's defintely better to call a variable "referenceCount" instead of "intRC". The point being that the type of a variable doesn't help you very much in understanding its purpose.

In my company I'm known for the guy with the annoying descriptive function names. I actually use functions like TransformPortionTextFromRTFToDisplay. Well, some people hate it (me too when I can't copy-paste the function name ), but it makes the code very readable.

[AnthonyMai]

I don't use other prefixes. for the exact reason offered by cup: How do you represent a pointer to an array of pointers anyway?!?! So much for clarity!

I would use pMyObjPtrArray for it. It's a million times better than MyValue or something like that.

The idea is still valid that prefixing/suffixing variable names help with the readability. And as long as you want, you can use a name that clearly spell out what it is (the data type) and what it does.

I can't believe that some one consider attaching a u or i in front of a variable is a waste of time. How much time could you have wasted in typing one extra character? By omitting that one character in variable name you could easily waste a few days instead of a few hours in tracking down a dummy coding bug.

Here is an example. Can you tell what is wrong with this code:

    if (myValue < 0)
    {
        // Do something
    }
    else
    {
        // Do something else
    }

You can't tell what's wrong? It is so obvious what's wrong to me by just glacing at it. But you could probably look at it one hundred times and still don't know what's wrong. Now let's try it slightly differently. See this time if you can tell me what's wrong?

    if (uMyValue < 0)
    {
        // Do something
    }
    else
    {
        // Do something else
    }

You see? You see!!! By adding an extra u, it immediately becomes crystal clear that the abobe code must be wrong. u means unsigned unmber. An unsigned integer could never ever be smaller than zero. So the logic of above code must be wrong. If this is a bug, I can spot in in one minute by looking at the u, and you could be spending several days without realizing this is a problem.

But you won't see me prefix any DWORDs with dw, ints with int or these things. Most of the time they are not really relevant.
I read that Herb Sutter link by Graham and it does make sense to me that in the days of OOP you should not have to use these prefixes anymore.

Forget about the OOP crap. Programming still boils down to basic manipulations of integers and doubles and signed or unsigned chars. Can you not pay attention to your data type?

You would pretty soon hate yourself for not prefixing DWORDs with dw, when you confuse a signed 4 bytes integer with an unsigned one, or when you started to try to make it work in a 64 bits operating system.

At minimal you should prefix something to tell whether the number is a signed or unsigned integer. Because in many cases signed or unsigned makes a big difference. Certainly if you never used an integer for any thing larger than what you could count with your fingers, that's another story.

[David Bajgar]

Oohhh, I don’t want to cause this flame war. But thanks for all opinions, they are very interesting.
Well, this is an idea from my boss. He wants to unify a writing of codes in our company. The main reason is: the code must be better readable for others in the company. If a programmer leaves the company others must be able to read his code. I think it is impossible to include all aspects of coding; it is not import if the variable is called mph_xx or phm_xx (btw. I think it should be m_phX).
I am sure this convention doesn’t cause that the code will be readable without problems, for that the code must contain a lot of comments of algorithms, functions etc. But I think it can help to understand the code better. If the variable is called “m_hMainThread” it is more readable than it is called “MainThread”.
The other point of view there is the experience. Senior programmer which is used to write code in first way he doesn’t want to write code in second way. I am sure it will bring the chaos into his code.
Of course, it is my point of view.

David

[PaulWendt]

Originally posted by proxima centaur
I totally disagree, and I think this is exactly the assumption everybody does and shouldn't. We all don't think alike!

What do you use as a prefix for a string? I've seen sz and I've seen plain s. To most of my colleagues coming from a Visual Basic background, s was the way to go, whereas for fellow C programmers, sz was unquestionable. Then, there was me, I chose s because it was 1 letter less to type

Like I said, there is a way to MANDATE which prefixes you use in
your organization. Just because there are different dialects of
Hungarian Notation doesn't mean that your organization can't
specify the rules for all of its employees to follow. Furthermore,
Hungarian Notation is NOT complicated once you get used to
SEEING a prefix in front of a variable name ... so changing from
nValue to iValue wouldn't be that big of a deal for someone used
to a different dialect.

As I also pointed out, even Microsoft programmers don't all use the same notation for the same variable types.

See above.

That's all that counts if you work alone.
If it works for others who will use your code, it's better

You have to make it work. If you're not in a position where you
get to make the decisions, then you all should come to some sort
of agreement, whether you use Hungarian Notation or not.

Frankly, I don't even use it excepting m_ and g_; I don't often
NEED the type of the variable in my variable name. The point I
was trying to make is that the different flavors of Hungarian
Notation are so similar that reading another flavor [and getting
used to it so that you use it on a constant basis] wouldn't be
too difficult.

--Paul