Rob Pike's simple Include rule

Re: Rob Pike's simple Include rule

Neil Cerutti wrote:[color=blue]
> Simple rule: include files should never include include
> files.
>
> Is following this guideline facile or hassle?[/color]

Definitely a hassle, and the only real gain is to avoid polluting the
namespace; the quoted benefit (prevention of multiple inclusion) does
not matter one whit, as you can accomplish it with some pre-processor
directives, as you note.

For the real problem (namespace pollution), one should document which
headers are included by each.

--
++acr@,ka"

Re: Rob Pike's simple Include rule

On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo. com> wrote:
[color=blue]
>In Rob Pike's style guide he urges the following:
>
> Simple rule: include files should never include include
> files. If instead they state (in comments or implicitly)
> what files they need to have included first, the problem of
> deciding which files to include is pushed to the user
> (programmer) but in a way that's easy to handle and that,
> by construction, avoids multiple inclusions.
>
>I was startled by this guideline, since it's not what I think of
>as the usual practice, i.e., brute-force idempotency through
>header guards in the headers.[/color]

FWIW, I disagree with Rob Pike on this issue. I believe an include
file should include whatever other headers it itself needs. However,
it shouldn't include any others. Finding after the first compile that
some header file needed another header included in front of it is
legitimate grounds for cursing the author.[color=blue]
>
>I have three questions about this advice, for those who use a
>similar style:
>
>1. Is following this guideline facile or hassle? I converted a
>simple two-header program over to this style, making several
>errors along the way. I clearly don't have experience
>with it.
>
>2. How does a header state implicitly what it requires for
>headers? I assume he means that you gleen this information by
>reading the header file, but I want to make sure I'm not missing
>something interesting.
>
>It seems like a good candidate for automation.[/color]

What's the third question? :-)

--
Al Balmer
Balmer Consulting
removebalmercon sultingthis@att .net

Re: Rob Pike's simple Include rule

"Neil Cerutti" <horpner@yahoo. com> wrote in message
news:c6948r$9gm ec$1@ID-60390.news.uni-berlin.de...[color=blue]
> In Rob Pike's style guide he urges the following:
>
> Simple rule: include files should never include include
> files. If instead they state (in comments or implicitly)
> what files they need to have included first, the problem of
> deciding which files to include is pushed to the user
> (programmer) but in a way that's easy to handle and that,
> by construction, avoids multiple inclusions.
>
> I was startled by this guideline, since it's not what I think of
> as the usual practice, i.e., brute-force idempotency through
> header guards in the headers.[/color]

Header guards are cheap and don't require extra vigilance on the part of the
programmer using your library. I've worked on a couple open-source projects
where include dependencies were a nightmare until I added header guards to
all the files and just brute-force included things in headers as needed.

What are the counter-cases where header guards are NOT the most efficient
solution?

S

--
Stephen Sprunk "Stupid people surround themselves with smart
CCIE #3723 people. Smart people surround themselves with
K5SSS smart people who disagree with them." --Aaron Sorkin

Re: Rob Pike's simple Include rule

Neil Cerutti wrote:
[color=blue]
> In Rob Pike's style guide[/color]



I just read Rob Pikes style guide
and I recommend that you ignore it.

Re: Rob Pike's simple Include rule

In article <u4cg80pa4r66j7 7h7epn1sao6pcso kmao3@4ax.com>, Alan
Balmer wrote:[color=blue]
> On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo. com> wrote:[color=green]
>>In Rob Pike's style guide he urges the following:
>>
>> Simple rule: include files should never include include
>> files.
>>
>>I have three questions about this advice, for those who use a
>>similar style:
>>
>>1. Is following this guideline facile or hassle?
>>
>>2. How does a header state implicitly what it requires for
>>headers?[/color]
>
> What's the third question? :-)[/color]

Oops.

3. What is the average air-speed velocity of an unladen sparrow?

--
Neil Cerutti
"Do you wanna see 'em?"
"See what?"
"The corpses. They're in the basement." --_Return of the Living Dead_.

Re: Rob Pike's simple Include rule

Neil Cerutti wrote:
[color=blue]
> In Rob Pike's style guide he urges the following:
>
> Simple rule: include files should never include include
> files. If instead they state (in comments or implicitly)
> what files they need to have included first, the problem of
> deciding which files to include is pushed to the user
> (programmer) but in a way that's easy to handle and that,
> by construction, avoids multiple inclusions.
>
> I was startled by this guideline, since it's not what I think of
> as the usual practice, i.e., brute-force idempotency through
> header guards in the headers.[/color]

In our shop we have the types
UINT8, UINT16, UINT32
defined a unsigned integers with the given bitwidth.

We have one file, let's say types.h, which defines those types
for various platforms.

So if I write a function:
UINT8 Public_Function (UINT16 variable)
{
/* ... */
}

and I want to make it public, I put it into a header file
my_functions.h:
UINT8 Public_Function (UINT16 variable);

Now, since it uses the UINT8 and UINT16 in the declaration,
those identifiers must be resolved before this function
declaration.

According to the style guide, a programmer must include
the types.h file before the my_functions.h file.

If the my_functions.h file has the statements:
#ifndef UINT8
#include "types.h"
#endif
before the function declaration, the user only has to
worry about including one function. The header file
takes care of its own declaration issues.


--
Thomas Matthews

C++ newsgroup welcome message:

C++ Faq: http://www.parashift.com/c++-faq-lite
C Faq: http://www.eskimo.com/~scs/c-faq/top.html
alt.comp.lang.l earn.c-c++ faq:

Other sites:
http://www.josuttis.com -- C++ STL Library book

Re: Rob Pike's simple Include rule

Neil Cerutti wrote:[color=blue]
> Alan Balmer wrote:[color=green]
>> Neil Cerutti <horpner@yahoo. com> wrote:
>>[color=darkred]
>>> In Rob Pike's style guide he urges the following:
>>>
>>> Simple rule: include files should never include include
>>> files.
>>>
>>> I have three questions about this advice, for those who use a
>>> similar style:
>>>
>>> 1. Is following this guideline facile or hassle?
>>>
>>> 2. How does a header state implicitly what it requires for
>>> headers?[/color]
>>
>> What's the third question? :-)[/color]
>
> Oops.
>
> 3. What is the average air-speed velocity of an unladen sparrow?[/color]

Approximately 27 kilofurlongs per fortnight.

--
Chuck F (cbfalconer@yah oo.com) (cbfalconer@wor ldnet.att.net)
Available for consulting/temporary embedded and systems.
<http://cbfalconer.home .att.net> USE worldnet address!

Re: Rob Pike's simple Include rule

On Fri, 23 Apr 2004 16:19:41 GMT, Thomas Matthews
<Thomas_Matthew sSpitsOnSpamBot s@sbcglobal.net > wrote:
[color=blue]
>According to the style guide, a programmer must include
>the types.h file before the my_functions.h file.
>
>If the my_functions.h file has the statements:
> #ifndef UINT8
> #include "types.h"
> #endif
>before the function declaration, the user only has to
>worry about including one function. The header file
>takes care of its own declaration issues.[/color]

Exactly. But you say this is contrary to your style guide?

Better yet, imo, if the types.h file had a header guard, the
#ifndef/#endif in my_functions.h would be unnecessary.

--
Al Balmer
Balmer Consulting
removebalmercon sultingthis@att .net

Re: Rob Pike's simple Include rule

Alan Balmer wrote:
[color=blue]
> On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo. com> wrote:
>
>[color=green]
>>In Rob Pike's style guide he urges the following:
>>
>> Simple rule: include files should never include include
>> files. If instead they state (in comments or implicitly)
>> what files they need to have included first, the problem of
>> deciding which files to include is pushed to the user
>> (programmer) but in a way that's easy to handle and that,
>> by construction, avoids multiple inclusions.
>>
>>I was startled by this guideline, since it's not what I think of
>>as the usual practice, i.e., brute-force idempotency through
>>header guards in the headers.[/color]
>
>
> FWIW, I disagree with Rob Pike on this issue. I believe an include
> file should include whatever other headers it itself needs. However,
> it shouldn't include any others. Finding after the first compile that
> some header file needed another header included in front of it is
> legitimate grounds for cursing the author.
>[color=green]
>>I have three questions about this advice, for those who use a
>>similar style:
>>
>>1. Is following this guideline facile or hassle? I converted a
>>simple two-header program over to this style, making several
>>errors along the way. I clearly don't have experience
>>with it.
>>
>>2. How does a header state implicitly what it requires for
>>headers? I assume he means that you gleen this information by
>>reading the header file, but I want to make sure I'm not missing
>>something interesting.
>>
>>It seems like a good candidate for automation.[/color]
>
>
> What's the third question? :-)
>[/color]
Conjecture: The source of Pike's guideline may not
have been addressing C-language per se, but rather
external factors, such as the "make" program.
(Which makes this OT in c.l.c, I guess.)

The earliest versions of "make" only checked for
explicit dependencies as specified in the "makefile".

Thus, if a.c included a.h which included b.h *and*
b.h was not an explicit dependency in the makefile,
then a.c would not get recompiled when b.h changed.
At best, you got a compile-time error. At worst,
you got undefined behavior or a core-dump after
delivery to the customer.

Developers were usually good about finding all the
#include directives in their own code in order to
create the makefile, but hardly ever checked whether
or not there were nested includes within other files.
This /may/ have been the reason for the guidelines
noted above.

More modern versions of "make" do this checking
for you. So if you have those versions, it has been
automated already.

--
"It is impossible to make anything foolproof
because fools are so ingenious"
- A. Bloch

Re: Rob Pike's simple Include rule

In <c6948r$9gmec$1 @ID-60390.news.uni-berlin.de> Neil Cerutti <horpner@yahoo. com> writes:
[color=blue]
>In Rob Pike's style guide he urges the following:
>
> Simple rule: include files should never include include
> files. If instead they state (in comments or implicitly)
> what files they need to have included first, the problem of
> deciding which files to include is pushed to the user
> (programmer) but in a way that's easy to handle and that,
> by construction, avoids multiple inclusions.
>
>I was startled by this guideline, since it's not what I think of
>as the usual practice, i.e., brute-force idempotency through
>header guards in the headers.
>
>I have three questions about this advice, for those who use a
>similar style:
>
>1. Is following this guideline facile or hassle?[/color]

It's a nightmare for both the implementor and the user. Consider
things like size_t and NULL, that are supposed to be available in
several headers: if the implementor wants to change one of them, he
must take care to change *all* the headers defining/declaring the
identifier in question.
[color=blue]
>2. How does a header state implicitly what it requires for
>headers?[/color]

If you see the following in a header:

void foo(FILE *);

then this header implicitly states that <stdio.h> must be included first.

I guess Pike was either drunken or stoned when he suggested that the
users of a header actually read the header in order to figure out its
dependencies.

Dan
--
Dan Pop
DESY Zeuthen, RZ group
Email: Dan.Pop@ifh.de

Re: Rob Pike's simple Include rule

CBFalconer <cbfalconer@yah oo.com> writes:[color=blue]
> Neil Cerutti wrote:[color=green]
> > Alan Balmer wrote:[color=darkred]
> >> Neil Cerutti <horpner@yahoo. com> wrote:
> >>
> >>> In Rob Pike's style guide he urges the following:
> >>>
> >>> Simple rule: include files should never include include
> >>> files.
> >>>
> >>> I have three questions about this advice, for those who use a
> >>> similar style:
> >>>
> >>> 1. Is following this guideline facile or hassle?
> >>>
> >>> 2. How does a header state implicitly what it requires for
> >>> headers?
> >>
> >> What's the third question? :-)[/color]
> >
> > Oops.
> >
> > 3. What is the average air-speed velocity of an unladen sparrow?[/color]
>
> Approximately 27 kilofurlongs per fortnight.[/color]

Actually, it's about 60 to 66 kilofurlongs per fortnight
(10 to 11 meters/second).

<http://www.style.org/unladenswallow/>

--
Keith Thompson (The_Other_Keit h) kst-u@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
Schroedinger does Shakespeare: "To be *and* not to be"

Re: Rob Pike's simple Include rule

In article <c6blav$28k$11@ sunnews.cern.ch >, Dan.Pop@cern.ch (Dan Pop)
wrote:
[color=blue]
> In <c6948r$9gmec$1 @ID-60390.news.uni-berlin.de> Neil Cerutti
> <horpner@yahoo. com> writes:
>[color=green]
> >In Rob Pike's style guide he urges the following:
> >
> > Simple rule: include files should never include include
> > files. If instead they state (in comments or implicitly)
> > what files they need to have included first, the problem of
> > deciding which files to include is pushed to the user
> > (programmer) but in a way that's easy to handle and that,
> > by construction, avoids multiple inclusions.
> >
> >I was startled by this guideline, since it's not what I think of
> >as the usual practice, i.e., brute-force idempotency through
> >header guards in the headers.
> >
> >I have three questions about this advice, for those who use a
> >similar style:
> >
> >1. Is following this guideline facile or hassle?[/color]
>
> It's a nightmare for both the implementor and the user. Consider
> things like size_t and NULL, that are supposed to be available in
> several headers: if the implementor wants to change one of them, he
> must take care to change *all* the headers defining/declaring the
> identifier in question.
>[color=green]
> >2. How does a header state implicitly what it requires for
> >headers?[/color]
>
> If you see the following in a header:
>
> void foo(FILE *);
>
> then this header implicitly states that <stdio.h> must be included first.
>
> I guess Pike was either drunken or stoned when he suggested that the
> users of a header actually read the header in order to figure out its
> dependencies.[/color]

I prefer the rule that

#include "header.h"

as the first line in a source should compile without error for every
header file, and that changing the order of "#include"s should not make
any difference.

Re: Rob Pike's simple Include rule

"Nick Landsberg" <hukolau@NOSPAM .att.net> wrote in message
news:jZbic.1424 9$_o3.463421@bg tnsc05-news.ops.worldn et.att.net...[color=blue]
> Alan Balmer wrote:
>[color=green]
> > On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo. com> wrote:
> >
> >[color=darkred]
> >>In Rob Pike's style guide he urges the following:
> >>
> >> Simple rule: include files should never include include
> >> files. If instead they state (in comments or implicitly)
> >> what files they need to have included first, the problem of
> >> deciding which files to include is pushed to the user
> >> (programmer) but in a way that's easy to handle and that,
> >> by construction, avoids multiple inclusions.
> >>[/color][/color][/color]

/snip/
[color=blue]
> Conjecture: The source of Pike's guideline may not
> have been addressing C-language per se, but rather
> external factors, such as the "make" program.
> (Which makes this OT in c.l.c, I guess.)
>
> The earliest versions of "make" only checked for
> explicit dependencies as specified in the "makefile".
>
> Thus, if a.c included a.h which included b.h *and*
> b.h was not an explicit dependency in the makefile,
> then a.c would not get recompiled when b.h changed.
> At best, you got a compile-time error. At worst,
> you got undefined behavior or a core-dump after
> delivery to the customer.[/color]

I would think that most developers using MAKE would
have added a dependency line specifying that a.h
depends on b.h, with a "touch" command that will
make a.h current (thus trigging a compile for a.c).

Re: Rob Pike's simple Include rule

Keith Thompson wrote:[color=blue]
> CBFalconer <cbfalconer@yah oo.com> writes:[color=green]
> > Neil Cerutti wrote:
> >[/color][/color]
.... snip ...[color=blue][color=green][color=darkred]
>>>
>>> 3. What is the average air-speed velocity of an unladen sparrow?[/color]
>>
>> Approximately 27 kilofurlongs per fortnight.[/color]
>
> Actually, it's about 60 to 66 kilofurlongs per fortnight
> (10 to 11 meters/second).
>
> <http://www.style.org/unladenswallow/>[/color]

I was that far off huh. Not too bad for a blind stab with no
furlong sparrows frolicing outside my window for the past
fortnight.

What about max. accelleration, in kf/fn^2?

--
Chuck F (cbfalconer@yah oo.com) (cbfalconer@wor ldnet.att.net)
Available for consulting/temporary embedded and systems.
<http://cbfalconer.home .att.net> USE worldnet address!