Pointless Blathering : Code

Pedantic Coder: Hungarian Notation

PeterWie — Mon, 13 Oct 2008 18:00:00 GMT

I generally dislike Hungarian Notation. I particularly dislike what Wikipedia calls "System Hungarian", where the prefix indicates data type, as it adds almost no value for me. I dislike the more semantically oriented form of Hungarian notation where the prefix implies some broader attribute (like "safety") because, though that does provide some value - I'm generally not fond of terse prefixes. If something is an unsafe X then call it "unsafeX", not "uX" hoping that a reader will know u means unsafe.

I have taken to including units in variable names when they're (a) beyond what the underlying C/C++ types can discriminate between and (b) too basic to warrant the creation of a class. For example, when a timeout is in milliseconds or microseconds i'll name the variable "timeoutMs" or "timeoutUs" so that I know which units the value is in. I don't think that a "time" class is adding enough value here to create one and deal with publishing it, making it available for all the public interfaces I define, figuring out how to make it usable for C developers, etc... But the difference between Ms and Us is quite large (both literally and figuratively).

When I do annotate variable names i tend to use suffixes - I find it's easier (for me) to parse a list of names if the real variable name comes first. A block of variables named msX, msY, msZ, ... is simply harder to read.

Despite this there's one set of terse suffixes that I have started using religiously - Cb, Cch & Ce. These are count-of-bytes, count-of-characters and count-of-elements. I have started using these everywhere in place of more general terms like "length" or "size" to indicate a counter for another variable. I think about these as another form of unit, and it has saved my butt a couple of times – particularly if you start using the safe-string functions since you can easily see that your “length” matches the same units as the string function you’re calling.

Code

PeterWie — Wed, 06 Feb 2008 01:33:03 GMT

Perhaps I'm just out of ideas, but I've decided to write about my coding style.

Coding style is usually a very personal thing, like any writing style. And as it usually causes some to foam at the mouth when brought up, I also wanted to put out this little disclaimer before I start.

You may agree with how I've chosen to do things, you may disagree, you may not care in the least. Please just take this as writing by someone who has been writing code a while and who likes to think about the process of writing code and building software.

At the least this can help my blog live up to its name :)

Pedantic Coder : Where do braces go?

PeterWie — Tue, 05 Feb 2008 02:25:15 GMT

I've become rather pedantic about my coding style over the years. I've worked in a number of people's code, and have always felt most comfortable in the core NT code because of the consistency of formatting, naming, etc... This is a coding style that we often call "Cutler Normal Form" in deference to Dave Cutler.

Despite this I recently made a change in the way I place my braces around blocks of code. CNF says that braces go at the end of the line that will execute the code block, as follows:

if (foo) {
    do something;
} else {
    do something else;
}

I used to really like this style. It made it clear to me when the statement being evaluated was continued into the next block. Of course I always use braces, even when I only want one statement in the if or else clause, so this was a quick way to look and be sure i'd set things up correctly.

I've now transitioned over to:

if (foo) 
{
    do something;
} 
else
{
    do something else;
}

This was the preferred style of the folks in the UMDF group when I joined the project. It took me a while to warm up to this. However i eventually found two things that i like about it.

First it leaves more open white space. In my "old age" (i.e. mid thirties) i find that i like more whitespace in my code. It improves the readability for me, and makes me work harder to keep my functions fitting on a single page - which is a good threshold for whether they're understandable or not.

The second is that it makes it much, much easier to put part of the block under an IFDEF. This to me was the winner. Now i can do:

#if bar
if (foo)
{
    do something specific to bar;
}
else
#endif
{
    do something else;
}

Rather than:

#if bar
if (foo) {
    do something specific to bar;
} else // note that there would otherwise be a { here
#endif
{
    do something else;
}

Or even worse:

#if bar
if (foo) {
    do something specific to bar;
} else {
#else
{
#endif
    do something else;
}

Perhaps it's a silly thing to change something as fundamental(ist) as brace formatting style to get around a little inconsistency in how you preprocess out part of a conditional. But i like consistency ... the hairs on the back of my neck go up when i see code that's not in my normal format. So in the end this made me more comfortable.

This has come up quite a bit for me when debugging something or refactoring something. When refactoring i'll frequently #if out a chunk of impacted non-critical functionality (usually replaced with a failure case) until i'm ready to deal with that chunk of code. For debugging it can be useful to do the same thing if you're trying to track down the cause of a crash and are at your witts end.

And I've come to find it prettier.

-p