How to name variables which are structs

Question

Hello,

i often work on private projects using the WinApi, and as you might know, it has thousands of named and typedefed structs like MEMORY_BASIC_INFORMATION.

I will stick to this one in my question, what still is preferred, or better when you want to name a variable of this type. Is there some kind of style guide for this case?

For example if i need that variable for the VirtualQueryEx function.

Some ideas:

 MEMORY_BASIC_INFORMATION memoryBasicInformation;   
 MEMORY_BASIC_INFORMATION memory_basic_information;

Just use the name of the struct non capitalized and with or without the underlines.

MEMORY_BASIC_INFORMATION basicInformation;
MEMORY_BASIC_INFORMATION information;

Short form?

 MEMORY_BASIC_INFORMATION mbi;

I often see this style, using the abbreviation of the struct name.

 MEMORY_BASIC_INFORMATION buffer;

VirtualQueryEx defines the third parameter lpBuffer (where you pass the pointer to the struct), so using this name might be an idea, too.

Cheers

Answer 1

I think it depends upon a number of issues, and you just have to find the best balance when striving for readability.

1. Window width
2. Variables/types of similar names used in the routine.

That being said, if I can get away with it, I would probably use ...

MEMORY_BASIC_INFORMATION  info;

If there were other similar types or variable names, then I would add some sort of descriptive modifier such as ...

MEMORY_BASIC_INFORMATION  memBasicInfo;

Or, if window real-estate was limited (some projects I have worked on have insisted upon 80 char line maximum), I could go for ...

MEMORY_BASIC_INFORMATION  mbi;

But to make it as readable as possible, I try to be consistent--and that I think is one of the most important things to keep in mind.

A little all over the place, but I hope it helps.

Answer 2

In general, it's discouraged to name variables based on their type. Instead, try to provide additional information about the specific context and purpose of the usage.

Using the MEMORY_BASIC_INFORMATION example, consider what the context is of the structure. Are you using the information to iterate over a number of such information structures? Then maybe

MEMORY_BASIC_INFORMATION currentFrame;

Or if you're performing a test on the memory info for some status, maybe it's a candidate.

MEMORY_BASIC_INFORMATION candidate;

Now you can write documentation like "test candidate structure for ...".

You may find that you still want to include type information using the type prefix location. If this is the case, you might call it mbiCurrentFrame or mbiCandidate.

If the purpose or context is truly abstract, such as is the case with the API functions themselves, I would chose something simple and direct, such as info or buffer, except in the case where those names could somehow be misinterpreted in the context.

Answer 3

Try and keep the case and acronym of the typedef, e.g.

MEMORY_BASIC_INFORMATION MBI_temp

I deal with a lot of code that is and must remain portable across Linux and Windows, this was also a problem for us.

You could also do it in camel case:

MEMORY_BASIC_INFORMATION MBITemp

.. but that doesn't seem as self explanatory.

The point is, anyone familiar with those structures should recognize them as what they are rather quickly. Just be sure not to tromp on another namespace.

The key is, just be consistent in each tree that you work on. Its really only a noticeable issue in two cases:

1. Globals
2. Mile long functions

If you have functions so long that you have to scroll up five pages to the declarations just to see what a variable is, there's larger problems to deal with than variable nomenclature :)

Annoyingly, this might introduce some weirdness due to syntax highlighting picking it up as a constant, but that's also the case for the underlying typedef.