Style guides for C and/or C++

[Keith Thompson]

This is unarguably a down side. How bad it is, though, is debatable.
When moving code between systems like this, something has to change
and if the library author has re-organised the code for the new port
then they will also have documented the new required includes (if they
are using Pike's rule).

[...]

That last "if" is, I think, another big problem with Pike's rule.
I suspect it's impractical to follow it unless *all* the code in the
project does so. In practice, most programmers (including library
developers) don't follow Pike's rule. If you try to follow it
yourself, you're going to end up with a mixture of headers that
#include everthing they need and headers that don't #include
anything.

It also depends on header authors to document exactly what other
headers the client needs.

 

[Tim Rentsch]

Nick Keighley <[email protected]> writes:

[... the rob pike rule that include files not do other includes ...]

Good engineering (and programming
is a branch of engineering) requires well encapsulated abstractions. [...]
You don't need to read of
list of comments to work out what list of includes to use.

Here, I think, is the heart of the issue. If I design my
library/component/whatever so as to be as cleanly encapsulated as
possible then the rule in question simply does not come into play
because it won't need any other includes. The problem is that this

this is the "this" referred to later?

Yes, the only "this" in an earlier posting. (I'd checked.)

is
not always possible in C. [snip]

I found this last sentence surprising. Can you elaborate
or give an example of when it isn't possible to bundle
up an include file so nothing else needs to be included
to use it?

No, because that is not what I was trying to say. I was thinking of
this: consider, say, a file-tree walking interface. It can choose to
hide all the normal bit masks used by the stat function by providing
its own (just those that are needed to do things like find all FIFOs
or all plain files etc.) or it can choose to depend on sys/stat.h (or
whatever).

Okay, I'm with you so far.

I wanted to stress that there are two things going on, encapsulation
and dependence. Perfect encapsulation will mean there are next to no
dependencies between header files. Imperfect encapsulation is, for
perfectly sounds reasons, the norm for C program so there is an issue
with header files, one solution to which is Pike's rule.

Ah ha. I understand now why I didn't understand before.
The "this" in your earlier posting -- ambiguity there.

ISTM that the uses of "encapsulation" in Nick's posting and Ben's
posting are a shade different in their meanings. Certainly the sense
I got from Nick's comment was different from the sense I got from
Ben's comment. (Mind you, I'm not saying either one was better or
worse, or right or wrong, just that they are different.) That also
may have contributed to the confusion.

I'm a tad loose in my terminology. I necessarily consider information
hiding to be a form of ecapsulation. And I'm willing to consider
"encapsulation" to be lexical or semantic (syntactic?)

I figured out how to express the difference between the two
senses of "encapsulation":

1. It isn't necessary to know anything more.

2. It isn't possible to know anything more.

Again, I'm not claiming either of these definitions is better or
worse, only that the two uses struck me differently, one as
(1) and another as (2).

 

[Chris H]

I use 1TBS (the K&R indentation style) for indenting, because there
is nothing any closer to an authoritative standard to be had.
ISO?

There's
arguments for and against a whole lot of styles; the only way to resolve
it is to appeal to authority, and K&R are authority.

This is NOT correct unless you are living in the 1970's Things move on.
(Ask K,R & T)

BTW K&R1 of K&R2?

 

[Keith Thompson]

This is NOT correct unless you are living in the 1970's Things move on.
(Ask K,R & T)

BTW K&R1 of K&R2?

It hardly matters. K&R1, K&R2, and all versions and drafts of the
ISO C standard use the same brace style. For that matter, so do
Harbison&Steele <OT>and Stroustrup</OT>. This style is commonly
referred to as K&R style because they popularized it, or as the
1TBS (One True Brace Style) by many of those who find it superior
to other styles.

I strongly prefer the 1TBS myself, but I'm not dogmatic about it.
I use a very different style at work because I need to be consistent
with existing code.

 

[Seebs]

ISO?

ISO hasn't specified a brace style.

This is NOT correct unless you are living in the 1970's Things move on.
(Ask K,R & T)

They're still authority as to C style. Or rather, the closest we'll have.

BTW K&R1 of K&R2?

They use the same brace style.

-s

 

[Richard Bos]

ISO?

The ISO Standard gives very few examples where the difference between
the OTBS and Allman style is noticable, but where it does, it follows
K&R, as it ought. With, it must be noted, a rather idiosyncratic indent
of 6 spaces.

This is NOT correct unless you are living in the 1970's Things move on.

Where indent style is concerned, it is as true as ever.

BTW K&R1 of K&R2?

Don't act stupid. You know as well as anyone that it makes no
difference, in this respect.

Richard

 

[lawrence.jones]

The ISO Standard gives very few examples where the difference between
the OTBS and Allman style is noticable, but where it does, it follows
K&R, as it ought. With, it must be noted, a rather idiosyncratic indent
of 6 spaces.

The indent is actually 0.5 inches, which corresponds to roughly 6 spaces
in the 10 point type used for examples but roughly 5 spaces in the 12
point type used for the main text.

 

[Richard Bos]

The indent is actually 0.5 inches, which corresponds to roughly 6 spaces
in the 10 point type used for examples but roughly 5 spaces in the 12
point type used for the main text.

That's even more idiosyncratic!

Richard

 

[wolfgang.riedel]

The "simple rule" regarding include files isn't very practical, though I can
appreciate the logic and the sentiment. In practice there are too many
issues.

Second, the rule is, frankly, too simple. Should I force people to
separately include <stddef.h> because my header uses size_t? <limits.h> for
LONG_MAX? Many engineers will as a matter of course include <stdio.h>,
<stdlib.h>, and other boilerplate in the first few lines of their source

....
I second this!
One of my biggest nightmares in a largescale software project,
I joined, was a dependency on the order of includes.
Partly, because of decl of types like FILE - not a problem,
because I like to include system headers before lib headers (openssl,
curl)
before own ones - but not everytime and everywhere doable (win!),
partly of macros (OT.: like AF_INET or F_SETLK),
that you must redefine for some platforms).

So, I prefere my lib headers to be autonom - but this doesn't help
allways:
f.e. if structures have different size_t in a lib than in your main
program -
but, I know, this is posible to handle.

Greetings, Wolfgang