C coding style

[Love4Boobies]

I realize this is a delicate subject, but it still needs to be addressed. I've prepared a coding style guide for the wiki that I'd like you guys to review and perhaps vote on once it's ready. It doesn't just cover indentation, but also some important issues that affect the quality of the code.

If you have any suggestions/criticisms to make, it would be preferrable that you make them on the discussion page.

[Owen]

Code: Select all

void foobar(int a, int *b) {

is not K&R style.

Code: Select all

void foobar(int a, int *b) 
{

is K&R style. Yes, the style for function declarations is different from that for conditional blocks.

From a pure readability standpoint, I'd go for requiring that any if followed by an else use braces. Additionally, I'd required any control construct containing another control construct to use braces. That is,

Code: Select all

while((c = getchar()) != EOF)
        switch(c) {

would be

Code: Select all

while((c = getchar()) != EOF) {
        switch(c) {

[Tobba]

For braces, just dont do stuff like this and it should be fine:

Code: Select all

if (a)
       while (b)
              for (; d; e++)
              {
              }

[thepowersgang]

Since this is designed for readability, I would say put all the braces on their own line, so that if there is a non-braced if/while/for it is easy to tell.

[Solar]

Generally speaking, a good style guide is short, consistent, and free of "special cases".

As such, all style guides I've ever had a hand in do things like "always put braces", and "always put braces on seperate lines". (The latter because readability matters, while screen real estate, once at a premium with 800x600 or 640x400 resolutions, doesn't matter that much anymore today.)

The best possible style guide, however, is a line of options to pass to a specific reformatter (like indent or astyle).

As for sizeof, I disagree with the notion that "programmers need to remember that sizeof is an operator, not a function". For virtually all uses (except taking its address), the fact that sizeof is an operator doesn't really matter, and writing it like any other function adds consistency (instead of a special case to the style guide).

I wouldn't talk about what happens if a function taking no arguments is declared without "void". Anyone using K&R style declarations today is subject to capital punishment without further warning.

[bluemoon]

For Indentation I follow google's style that use SPACE instead of TAB; this make code looks more consistent across different editors.

And for Compiler-specific extensions, it depends on the project consideration. I would not go against people using them.

The best possible style guide, however, is a line of options to pass to a specific reformatter (like indent or astyle).

Good idea.

[Love4Boobies]

I can see everyone decided to ignore me when I asked that we use the discussion page, but that's ok

Code: Select all

void foobar(int a, int *b) {

is not K&R style.

Code: Select all

void foobar(int a, int *b) 
{

is K&R style. Yes, the style for function declarations is different from that for conditional blocks.

You are right, of course. I wrote that page in a hurry and that slipped in---weird, since I never write that. Thanks for pointing it out.

Generally speaking, a good style guide is short, consistent, and free of "special cases".

As such, all style guides I've ever had a hand in do things like "always put braces", and "always put braces on seperate lines". (The latter because readability matters, while screen real estate, that a premium with 800x600 or 640x400 resolutions, doesn't matter that much anymore today.)

My rule is pretty simple: Use braces when they are needed.

The best possible style guide, however, is a line of options to pass to a specific reformatter (like indent or astyle).

Maybe, but you still need to decide on the style first.

As for sizeof, I disagree with the notion that "programmers need to remember that sizeof is an operator, not a function". For virtually all uses (except taking its address), the fact that sizeof is an operator doesn't really matter, and writing it like any other function adds consistency (instead of a special case to the style guide).

That's not really true. E.g., consider the following:

Code: Select all

p_t *p = malloc(sizeof(*p));

This would result in undefined behavior were sizeof a function, as p doesn't point to anything at the first sequence point. As you can see, avoiding this confusion will help with such subtle problems. There are also a couple of other problems:

Code: Select all

sizeof(puts("hello, world!"));
&sizeof(foo);

although these are less realistic.

I wouldn't talk about what happens if a function taking no arguments is declared without "void". Anyone using K&R style declarations today is subject to capital punishment without further warning.

You're probably mixing up these two things:

Code: Select all

int foo(a)
int a;
{
}

// vs.

int bar( /* void */ )
{
}

The former was used in traditional C (i.e., before C89) and K&R have stopped using it as well, with the second edition of the book. I'm obviously against it as well.

For Indentation I follow google's style that use SPACE instead of TAB; this make code looks more consistent across different editors.

It's not just Google who will give you that advice, it's mostly any sane programmer. This is irrelevant for the wiki, though so it's off-topic.

[Combuster]

a good style guide is short, consistent, and free of "special cases".

• Always use braces
• Always place braces on the next line, always follow a brace with a newline.
• Every scope block and switch case is indented with 4 spaces.
• Code may not exceed 40 characters in width due to screen stretching
• C code must compile with gcc with the following quality-checking arguments: -std=c99 -pedantic -Wall -Werror
• Every high-level step, every design choice, and every input and output must be documented. Such documentation can either be placed in code comments or in the accompanying text (EDIT: this is worthy of being forum etiquette imo; no names)
• In-line comments use // exclusively (so that code disabling with both /*..*/ and #if 0 works)
• Compiler-specific extensions may only be used when it is the subject of discussion

[Love4Boobies]

Combuster seems to be describing the Allman style, which although is pretty good, I've decided to avoid in the guide due to the fact that I suspect less people are familiar/comfortable with it. Again, indentation seems to be a delicate subject for programmers and I wanted to "offend" as few as possible. I do have a couple of problems with it, namely:

• Indenting switch cases and then, again, the statements that follow them seems redundant.
• I'm still not convinced using braces for just one statement is sensible. It contradicts my principle of "don't do more than you're supposed to."

What are your views?

Second, looks like you write a style guide for noobies who don't know C. Who cares about sizeof, really?

People who want to avoid subtle bugs care about language semantics. You are making the wrong assumption that people contributing to the wiki aren't C newbies; if they weren't, <stdint.h> and proper serialization would be used more often (as far as I can tell, these two are the most popular mistakes).

[Combuster]

the fact that I suspect less people are familiar/comfortable with it. (...) What are your views?

I see a subjective argument in a religious debate.

Fact is, I pretty much copied it from Solar's post, and braces after newlines is the official policy at my work. Fact is also that the point is deliberately absent in the current manual of style.

[Solar]

I'm still not convinced using braces for just one statement is sensible. It contradicts my principle of "don't do more than you're supposed to."

What are your views?

My view is that you are "supposed to" use braces in all cases because it's 1) consistent, 2) more readable (partly due to 1)), and 3) avoiding the very kind of subtle bugs you're talking about with regards to sizeof().

By the way, let me extend the threat of capital punishment to people who use sizeof() on variable names instead of types.

And while we're at it, +1 for indenting with 4 spaces. Tab indents are hellish. I've set up my SVN repo to reject any file that contains tabs and is not named "Makefile".

And +1 +1 +1 +1 to Combuster's style guide. While my personal style differs from that a bit, that's the kind of short-and-concise style guide that is easy to follow.

[Solar]

I don't do refactoring.

At least not the partial type you're referring to.

No, I got your point. I withdraw that remark.

[Love4Boobies]

the fact that I suspect less people are familiar/comfortable with it. (...) What are your views?

I see a subjective argument in a religious debate.

Of course, but it's a necessary evil.

[Solar]

To get away from the "one true brace style" issue for a second, how about sprinkling some whitespaces over the whole thing? See my edit. IMHO, it adds lots to readability. Putting a space in front and after a pointer's asterix also avoids the other holy war you usually get when coding style is concerned...

[Love4Boobies]

I won't use spaces like that in my own code but it doesn't bother me if we do it on the wiki. As for the asterisk thing, the following might look a bit odd:

Code: Select all

int * a, * b, * c;

I think none of the decisions really matter that much since we're not talking about massive amounts of code. We might as well create a poll for how to handle braces and stick to that. If people reading the wiki don't like it... good. They're not supposed to copy & paste the code anyway.