Cuddle Your Braces

Variable Names in C Function Prototypes: Not a Good Idea

2007-10-10T06:26:00.000-07:00

It seems that some neophyte C programmers are unaware that variable names are not required (let alone not desired) in function prototypes. This also seems to happen when lazy programmers cut-and-paste the function head from the .c to the .h file and neglect to edit out the names.

The most obvious problem with this practice is that the names will need to be maintained in two separate files and can very easily get out of sync. Another is the general clutter the additional identifiers will create in the header files.

It is also poor documentation style to document a function twice, and variable names are a form of documentation--at least to those who pay attention to cultivating good documentation practices. This would be akin to providing a book with both footnotes at the bottom of each page and chapter notes at the end of each chapter containing redundant information. And what's worse still, is that the documentation process of code is usually integral with the programming of it: since the definitions are undergoing rapid changes during the process while the prototypes are relatively stable, the two tend to diverge significantly.

In addition to the maintenance nightmares caused by using variable names in two places, one must critically examine the purposes of the documentation, to whom it is addressed, and where the addressee goes to find it. The purposes will not be discussed here, but we do need to take a look at the last two. Documentation is addressed typically to clients and developers. The former will typically look to the manuals (either electronic or print media). To suggest they look in the header files is absurd--e.g. how many users of stdio.h look in that file for information on how to use printf()? Of course the developers would naturally document a function where it is defined rather than prototyped.

QED

Why the postfix increment operator in for loops is a bad idea

2007-09-28T11:19:00.001-07:00

The naive programmer writes:

for (i=0; i<100; i++)

to count from 0 to 99 while those who know better write

for (i=0; i<100; ++i)

There are two reasons for doing so. The first is on the grounds of efficiency: the postfix increment requires the creation of a temporary variable. Since the runtime value of i++ must different from i (i cannot be both values), the compiler will need to set aside space for a new variable and copy the original value of i to it.

Not only is it more efficient to use the prefix operator, but it is more elegant and semantically correct. The postfix increment says fetch me the value (which I don't have any need whatsoever for) of i and then when I'm done with it, then increment it; the prefix version simple says "increment the value of i."

It also translates better into proper English: ++i translates to "increment i" while i++ translates to the ungrammatical "i and increment" or the clumsy "evaluate i and then increment it."

The Evils of the while(true) loop

2007-09-27T11:41:00.000-07:00

There has been a disgusting tendency among some alleged programmers to write an endless loop as:

while (true) {
// do something
}

rather than the classic:

for (;;) {
// do something smarter than the above loop
}

The first form is not only an abuse of logic but an abuse of notation. Logically it suggests a loop that will go on forever because of some tautology--which has absolutely nothing to do with the logic of the program--used as its condition. In pseudocode:

while (all Greeks are Men) {
...
if (pigs can fly)
break;
}

In other words the condition in the while statement has nothing to do with the condition for exiting the loop. It is an abuse of notation since a while loop is really a syntactic sugar for the more general for loop in which a condition is expected to be false at some time during its execution.

Now, consider the beautiful, elegant:

for (;;) {
}

not only is it much more succinct than the former, but there is no need for some bogus condition for the loop check expression. It simply and clearly states that a loop will continue to iterate until some internal condition dictates that it is now time to break out.

Why it is important to cuddle your braces when writing code

2007-09-25T12:47:00.000-07:00

The Fundamental Theorem of Formatting states that the visual layout should show the logical structure of the program. As Steve McConnell says in his classic Code Complete the coding style where opening braces occur alone on a line beneath the conditional or loop statement they belong to (that if one is allowed certain liberties with the meaning of the word "style") violates this principle in that it suggests that the body of the conditional or loop is subordinate to the brace, rather than the for or the if statement that it belongs to!