Jump to content
  • Advertisement
Sign in to follow this  
lukesmith123

Naming Conventions

This topic is 2440 days old which is more than the 365 day threshold we allow for new replies. Please post a new topic.

If you intended to correct an error in the post then please contact us.

Recommended Posts

Does anybody know of any resources or could offer some advise on choosing naming conventions to make code more readable.

I dont want to use underscores because I find it hard to read.

my initial idea is to use the letter m to precede names of member variables in classes. But then I would have to break this if I had two variables of different types. Like a scale matrix and a scale vector couldnt both be called mScale.

are there any rules or guidelines to follow when doing this?

Share this post


Link to post
Share on other sites
Advertisement
mScaleVector and mScaleMatrix? There isn't anything too specific that I can think of in terms of rules and guidelines. Except this: without Intellisense, I should be able to know what a variable is used for/what it does without having to look at more than a couple lines. With Intellisense, I should be able to see the variable's data type, and it shouldn't surprise me.

Share this post


Link to post
Share on other sites
Not sure what language you're writing this in? Anyway, in addition to the obvious, I'd suggest having a look at the google style guide - not necessarily to adopt it, but because it provides a rationale for its choices.

Personally I think clarity should always win. Calling something 'scale' when there is an ambiguity as to whether it's a vector or a matrix, requires rethinking the ambiguity:
- should they be a hybrid type that exhibits both properties of a vector and a matrix?
- or should they be two members, in which case they need to be differentiated?

Like Cornstalks I'd go with the latter - at work our naming convention would make me call it FScaleMatrix, FScaleVector; at home it'd be scaleMatrix and scaleVector and at my old job it'd be m_matScale and m_vecScale. The 'm' is almost incidental...

Share this post


Link to post
Share on other sites
Naming a variable so it's clear that it's a class member is unnecessary.
If you have too many local variables that can cause confusion, then you need to split up your functions/methods in to smaller part.

As well as if you are consistent in your code you don't need to put Matrix or mat in the name of every declaration,
if scale always is a matrix then you should know that.

Stop thinking about how to restrict yourself and just start creating

Share this post


Link to post
Share on other sites
Many people have been asking me to write such a guideline. If I had done so, it would have been helpful here, so I think I will do it soon.

No offense Molle85, but that is not helpful.
If he knows what scale is, and he always makes it that:
#1: Is he not even more restricted?
#2: He and only he knows his code. Naming conventions are not just to help yourself. So he knows what scale is. That isn’t much help to him 2 years from now, nor is it much help for the next guy or girl to view his code.

Class member prefixes are helpful. Very, in fact.


Here are a few suggestions to the original poster, in condensed form:
m_ = Member prefix.
_ = Parameter prefix.
p = Pointer
u = Unsigned.
i = Int.
32 = bits in the type.
f = Float.
d = Double.


Examples:
m_pui32CurPos = Pointer to a 32-bit unsigned int, and it is a class member.
i32Total = 32-bit integer. Not a member of a class and not a parameter.
_ui8Mask = An 8-bit unsigned integer that was passed to the function.



Any naming convention guideline is just that—a guideline. You can feel free to change what you want to suit your personal taste, but the above gives you things to consider and what types of things your naming convention may want to document.
m_ and _ document the origin of the variable.
p documents the fact that it is a pointer.
ui, i, f, and d document the type.
8, 16, 32, and 64 document the size.
C documents that a type is a class.


My guide will also go into details such as:
#1: Put all enumerations first within their scope, then any new structures/typedefs, then members, then functions. Members and functions can be swapped, but enumerations should always be first because structures, functions, and types can rely on them, but enumerations cannot rely on functions, members, or types.
Next comes structures/typedefs, because functions and members can rely on types, but types cannot rely on functions/members.
#2: Make your public class interfaces top of the class declaration, then protected, then private. Follow guideline #1 within these 3 areas respectively.
#3: Use a small comment to indicate your transition from enumerations to types to functions. For example: “// == Enumerations.” After this comment, put all of your enumerations for that scope. Then use “// == Types.”, followed by all of the types you want to declare. “// == Functions.” and “// == Members.” follow.


These are all just things to consider, but one thing on which everyone can agree: When you pick a style, be consistent in that style. A style is useless if it cannot be trusted.


L. Spiro

Share this post


Link to post
Share on other sites
Naming a variable so it's clear that it's a class member is unnecessary.
If you have too many local variables that can cause confusion, then you need to split up your functions/methods in to smaller part.
It depends on the kind of programming you're doing.
E.g. here's some code that gets an array of integers, sums the values, and fills the array with 0's.uint numInputs = 0;
int* inputs = GetInputs(&numInputs);
for( int j=0; j<numInputs; ++j )
{
count += inputs[j];
inputs[j] = 0;
}
Just by glancing at this section of the code, the reader can't see the should-be-obvious performance pitfall. The reader has to take in the entire function, and then use a process of elimination to determine that '[font="Lucida Console"]count[/font]' is probably a member variable because it's not a local, and then notice the horrible pointer-aliasing between '[font="Lucida Console"]this->count[/font]' and '[font="Courier New"]inputs[/font]' and fix the performance bug (i.e. after writing to [font="Lucida Console"]inputs[/font], the compiler can't be sure that the value of [font="Lucida Console"]this->count[/font] is the same as the previous iteration of the loop, forcing it to re-load the member from RAM continually, making the loop 10x slower -- writing into a local, then copying the local to the member will fix this -- an '[font="Lucida Console"]m[/font]' would've made this bug stand out to the reader instantly).

If you're writing the kind of code where you don't have to care what the hell pointer aliasing is, then your needs might be different. If you're doing some kind of programming that requires stupidly long functions, you might want to go as far as using an '[font="Courier New"]a[/font]' prefix on argument-variables, as well as an '[font="Courier New"]m[/font]' prefix on members. If you're doing OO in a non-OOP language, you won't need 'm' prefix as you'll always be using "[font="Courier New"]self.[/font]" etc... Likewise, if you're doing the kind of programming where the size and type of variables is extremely important, then perhaps you should use the horrible MS systems-hungarian style.
A good style should be expressive of the kind of code it's used to write.

Share this post


Link to post
Share on other sites
Personal opinion: no to what YogurtEmporer said (in general). Systems Hungarian notation for data types is, in my opinion, an abomination.
^^ Fixed that for you. "Apps Hungarian" is still widely used, due to it not being an abomination wink.gif

Share this post


Link to post
Share on other sites

[quote name='Cornstalks' timestamp='1316396659' post='4863201']Personal opinion: no to what YogurtEmporer said (in general). Systems Hungarian notation for data types is, in my opinion, an abomination.
^^ Fixed that for you. "Apps Hungarian" is still widely used, due to it not being an abomination wink.gif
[/quote]
Yeah, maybe I should've clarified that. I was referring to systems Hungarian (when I said "for data types", I meant using the data's type as part of the variable name). Apps Hungarian can be useful, and while I still don't like how it mangles variable names, if mangling a variable name is what you need to protect your site from a SQL injection, for example, then it's well worth it.

Share this post


Link to post
Share on other sites
Sign in to follow this  

  • Advertisement
×

Important Information

By using GameDev.net, you agree to our community Guidelines, Terms of Use, and Privacy Policy.

Participate in the game development conversation and more when you create an account on GameDev.net!

Sign me up!