Help with Naming Conventions

[Daz]

Hi all!

This question may hopefully spark a little debate, but my problem is
this:

I am sure it's not just me who struggles to think up names for
variables. Obviously, thinking up a name 'can' be simple, but when you
are trying to create variable names that are easy to remember,
descriptive, and not more than say 15-20 characters long, I come a
cropper! Would anyone be able to give me any pointers as to how I can
create the variable names I am looking for, or is it simply a case of
having a notepad doc open and keeping track of what each name is?

Any comments would be appreciated.

Daz

[Daniel Aarno]

Have you considered you might be writing too long functions or not structuring
your arguments together in logical groups enough. Generally most functions
should not be more than 10-50 lines of code and contain 5 variables or so. If
you can't come up with names that are not to long you can put comments for each
variable in the beginning and try to document your algorithm, not your code.
Same goes for arguments to functions, they should be descriptive and few
(otherwise consider grouping them in a struct). Example:

/* This would be a bad name */
void LoadFile(const char* nameOfInputFileToLoadTextureFrom);

/* This along with a comment like:
@param inFile name of input file to load texture from
would be better.
*/
void LoadFile(const char* inFile);

Of course these are rules of thumb and not everybody will agree with me. But
these are at-least my thought on the matter.

/Daniel Aarno
Daz skrev:

Hi all!

This question may hopefully spark a little debate, but my problem is
this:

I am sure it's not just me who struggles to think up names for
variables. Obviously, thinking up a name 'can' be simple, but when you
are trying to create variable names that are easy to remember,
descriptive, and not more than say 15-20 characters long, I come a
cropper! Would anyone be able to give me any pointers as to how I can
create the variable names I am looking for, or is it simply a case of
having a notepad doc open and keeping track of what each name is?

Any comments would be appreciated.

Daz

[Daz]

Daniel Aarno wrote:

Have you considered you might be writing too long functions or not structuring
your arguments together in logical groups enough. Generally most functions
should not be more than 10-50 lines of code and contain 5 variables or so. If
you can't come up with names that are not to long you can put comments for each
variable in the beginning and try to document your algorithm, not your code.
Same goes for arguments to functions, they should be descriptive and few
(otherwise consider grouping them in a struct).

Thanks for that Daniel, I appreciate your input. I think the main
problem I am trying to address more than anything is consistancy. The
only trouble being, I can't seem to find one easy way to name functions
and variables that suits every situation. Take Hungarian Notation for
example. It has it's good points and it's bad points. Some people
prefer it, others do not.

[mlimber]

Daz wrote:

Daniel Aarno wrote:

Have you considered you might be writing too long functions or not structuring
your arguments together in logical groups enough. Generally most functions
should not be more than 10-50 lines of code and contain 5 variables or so. If
you can't come up with names that are not to long you can put comments for each
variable in the beginning and try to document your algorithm, not your code.
Same goes for arguments to functions, they should be descriptive and few
(otherwise consider grouping them in a struct).

Thanks for that Daniel, I appreciate your input. I think the main
problem I am trying to address more than anything is consistancy. The
only trouble being, I can't seem to find one easy way to name functions
and variables that suits every situation. Take Hungarian Notation for
example. It has it's good points and it's bad points. Some people
prefer it, others do not.

Hungarian notation doesn't scale particularly well for user-defined
types, IMHO, and that is reason enough to discard it in C++. Daniel's
advice above is good. Listen to him.

Also, I prefer to name functions as Verb() or VerbObject() [e.g.,
Close(), SearchTree(), HasTerminated()]. The object-less versions are
more useful for member functions in the public interface of a class
since, e.g., there could be many things that need closing, but calling
file.Close() is clear and not redundant like file.CloseFile().

As for variables, keep them in as small a scope as possible, and you'll
prevent many name collisions and make things easier to follow. Most
programmers use some convention for identifying member variables such
as a trailing underscore or a leading m_, but beyond that, just use
meaningful names within that scope. Some also use a similar convention
for static and global objects.

You could adopt virtually any style and write readable code with it.
For instance, you might name a variable for holding the number of
elements elem_count, n_elems, arraySize, etc. All of these are fine --
just pick one style and go with it. Consistency is more important than
the particular style. One might choose to use underscores to separate
words (like the standard library does) over CamelCase (like Microsoft
does), and that's not really a big deal as long as you're consistent.

Cheers! --M

[Daz]

Vey clear, concise and makes perfect sense. Thanks very much.

[Daniel T.]

Daniel Aarno wrote:

Have you considered you might be writing too long functions or not structuring
your arguments together in logical groups enough. Generally most functions
should not be more than 10-50 lines of code and contain 5 variables or so.

10-50 lines of code seems like a lot to me. I rarely end up with a
member-function that has more than 10 lines of code, non-member (and
static member) functions tend to be a little bigger but still rarely
more than 20 lines.

To the OP, IMHO variable and function names should be written such that
they make sense at the point of use, I try to get it looking as much
like standard english as I can.

To expand on Mr Aarno's example: 'nameOfInputFileToLoadTextureFrom' is
not a bad name because it is long, but because it would be hard to
speak out loud the place where it is used...

textureFile.open(nameOfInputFIleToLoadTextureFrom) ;

If you were talking to someone named "textureFile" and you wanted him
to open a file how would you say that in English? I would probably say
something like "textureFile, please open this file name." Now of course
in code we don't need to be so polite (so "please gets dumped") and
pronouns are superfluous so we can dump "this"... You end up with
"textureFile, open file name." No convert that back to code:

textureFile.open( fileName );

Generally, I try reading the code out loud as English, if it doesn't
make sense, then I need to change the names of some
functions/variables.

[Shimon Shvartsbroit]

Daniel T. wrote:

Daniel Aarno wrote:

Have you considered you might be writing too long functions or not structuring
your arguments together in logical groups enough. Generally most functions
should not be more than 10-50 lines of code and contain 5 variables or so.
10-50 lines of code seems like a lot to me. I rarely end up with a
member-function that has more than 10 lines of code, non-member (and
static member) functions tend to be a little bigger but still rarely
more than 20 lines.

To the OP, IMHO variable and function names should be written such that
they make sense at the point of use, I try to get it looking as much
like standard english as I can.

To expand on Mr Aarno's example: 'nameOfInputFileToLoadTextureFrom' is
not a bad name because it is long, but because it would be hard to
speak out loud the place where it is used...

textureFile.open(nameOfInputFIleToLoadTextureFrom) ;

If you were talking to someone named "textureFile" and you wanted him
to open a file how would you say that in English? I would probably say
something like "textureFile, please open this file name." Now of course
in code we don't need to be so polite (so "please gets dumped") and
pronouns are superfluous so we can dump "this"... You end up with
"textureFile, open file name." No convert that back to code:

textureFile.open( fileName );

Generally, I try reading the code out loud as English, if it doesn't
make sense, then I need to change the names of some
functions/variables.

First of all, I agree with Daniel T. You have to keep in mind that once
working in Object Oriented world, each object (or Entity) has set of
actions it can perform.
I also encourage the use of descriptive names. I enjoy orking with
Visual Assist (www.wholetomato.com). That way I can still keep
descriptive variable and member names without cost of coding time
that's spent on writing long variable names. Also, when I say
descriptive I mean that names can be long, but not redundant.
You can take VA for free trial and see how great it does work of code
suggestions and other miracles.

I beleive that code should tell a story. I think that Daniel Aarno
meant that as well. There's no point in commenting the obvious, like:

++i; // increment i

The above line has few goals:
1). distruct programmer from real program
2). making the code bigger and uglier
.. maybe some more.. but none of goals is good.

The most important thing to keep in mind, IMHO, is that you have naming
conventions and that everybody in your team, even if it's 1 men crew,
follows it.

When telling a story, there should be objects. Objects can talk with
other objects. Objects can do things, like loding a texture and more
on.. A good coding practice is to make functions short, as people
already mentioned, 10-20 lines. Each function should have a
well-defined purpose.

here's a brief sum of naming conventions I use:
s_someStuffGoingOn - static
m_blaFooWidget - member

void funcName(int i_inputData, const Widget& i_anotherInput, float&
o_outputData, bool& io_inputAndOutputData)
{
int localVar;
}

class Widget
{
static const int SOME_NUMBER = 17;

static int s_foo; // don't forget to define it in .cpp file
bool m_isActive;
public:
void invoke(const SomeObject& i_fear);
};

Though, it's my personal taste.. I beleive that many C++ programmers
use this convention as well.

Regards,
Shimon

[Jim Langston]

"Daz" <cu********@gmail.com> wrote in message
news:11**********************@y43g2000cwc.googlegr oups.com...

Hi all!

This question may hopefully spark a little debate, but my problem is
this:

I am sure it's not just me who struggles to think up names for
variables. Obviously, thinking up a name 'can' be simple, but when you
are trying to create variable names that are easy to remember,
descriptive, and not more than say 15-20 characters long, I come a
cropper! Would anyone be able to give me any pointers as to how I can
create the variable names I am looking for, or is it simply a case of
having a notepad doc open and keeping track of what each name is?

Any comments would be appreciated.

Variable names are generally easier, as they only have to make sense in
context.

void ReadPlayerFile( const std::string& Filename )

My function names are generally a verb and a noun. A verb as to what I'm
going to be doing to the noun. I think that ReadPlayerFile is perfectly
descriptive and doesn't even neeed any commenting. Filename is fine,
because if I want to know what filename, I just look at the function name,
it's the PlayerFile name of course.

Iterators I've decided on going with "it" with a prefix as to what it's an
iterator for, keeping them short. This stems from the age old concensus to
name for loop variables i. So I use it for iterators. Here's a few
examples of functions and paramters I'm using in my current program:

void SendHealthToPlayer( const CPlayer& ThisPlayer )
bool CheckIfPlayersHit( map_key_pcmissile::iterator& mit )
EBodyParts ChracterHit( const CCharacter& Char, const JVEC3& BeamPos )
void CheckLimb( const int Value, const int Max, bool& Disabled, bool&
Destroyed )
void ReadMapData( const std::string FileName, CMapValues& MapValues );
void SendMessageToPlayer( const SOCKET Socket, const BYTE MessageType, const
std::string& Message );
void SendMessageToGMs( const BYTE MessageType, const std::string& Message );
void SendMessageToRange( const int Map, const JVEC3 Pos, const BYTE
MessageType, const std::string& Message, const float Range = 0 );
void SendMessageToMap( const int Map, const BYTE MessageType, const
std::string& Message );
void SendMessageToWorld( const BYTE MessageType, const std::string&
Message );
void SaveServerData()
CMap& FindMap( const unsigned int MapNumber )
CPlayer& FindPlayer( const SOCKET Socket )
CNPC& FindNPC( const unsigned int ID )
CPlayer& FindPlayer( const std::string Name )
std::string trim( const std::string& text, const char TrimChar = ' ' )
std::string SendIfLongToPlayer( const SOCKET Socket, const BYTE MessageType,
const std::string SendMessage, const unsigned int MaxLength = 70 )
std::string CreateCharMessage( const unsigned int Key, const CCharacter&
Character )

[Daz]

Shimon Shvartsbroit wrote:

First of all, I agree with Daniel T. You have to keep in mind that once
working in Object Oriented world, each object (or Entity) has set of
actions it can perform.
I also encourage the use of descriptive names. I enjoy orking with
Visual Assist (www.wholetomato.com). That way I can still keep
descriptive variable and member names without cost of coding time
that's spent on writing long variable names. Also, when I say
descriptive I mean that names can be long, but not redundant.
You can take VA for free trial and see how great it does work of code
suggestions and other miracles.

I beleive that code should tell a story. I think that Daniel Aarno
meant that as well. There's no point in commenting the obvious, like:

++i; // increment i

The above line has few goals:
1). distruct programmer from real program
2). making the code bigger and uglier
.. maybe some more.. but none of goals is good.

The most important thing to keep in mind, IMHO, is that you have naming
conventions and that everybody in your team, even if it's 1 men crew,
follows it.

When telling a story, there should be objects. Objects can talk with
other objects. Objects can do things, like loding a texture and more
on.. A good coding practice is to make functions short, as people
already mentioned, 10-20 lines. Each function should have a
well-defined purpose.

here's a brief sum of naming conventions I use:
s_someStuffGoingOn - static
m_blaFooWidget - member

Though, it's my personal taste.. I beleive that many C++ programmers
use this convention as well.

Thanks for such a well-thought-out response. I think everyone works in
very similar ways. My functions tend to be a lot longer, and I think I
see why they should be smaller. It's easier to maintain the code for
starters, however, I can never think up decent enough names for my
functions, that are not long and ugly. Eventually, I get functions
named like 'function1' with a brief description of what it does. I
don't believe that this is an acceptable mannor of coding, but I can't
help thinking that many more 'smaller' functions would make the code
harder to follow without using a debugger.

Thanks for the reccomendation of Visual Assist. It sounds useful, and
although I am still a little unclear as to what it does exactly, I will
sure give it a go.

Many thanks.

Daz