Rob Pike's simple Include rule

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?  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.

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

Neil Cerutti wrote:
>    Simple rule: include  files  should  never  include  include
>    files.
>
> Is following this guideline facile or hassle?

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"

On 22 Apr 2004 18:52:12 GMT, 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.   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.

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.
>
>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.

What's the third question? :-)

--
Al Balmer
Balmer Consulting
removebalmerconsultingthis@att.net

"Neil Cerutti" <horpner@yahoo.com> wrote in message
news:c6948r$9gmec$1@ID-60390.news.uni-berlin.de...
> 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.

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

Neil Cerutti wrote:

> In Rob Pike's style guide

http://www.chris-lott.org/resources.../pikestyle.html

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

In article <u4cg80pa4r66j77h7epn1sao6pcsokmao3@4ax.com>, Alan
Balmer wrote:
> On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo.com> wrote: 
>
> What's the third question? :-)

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_.

Neil Cerutti wrote:

> 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.

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:
http://www.slack.net/~shiva/welcome.txt
C++ Faq: http://www.parashift.com/c++-faq-lite
C Faq:   http://www.eskimo.com/~scs/c-faq/top.html
alt.comp.lang.learn.c-c++ faq:
http://www.raos.demon.uk/acllc-c++/faq.html
Other sites:
http://www.josuttis.com  -- C++ STL Library book

Neil Cerutti wrote:
> Alan Balmer wrote: 
>
> Oops.
>
> 3. What is the average air-speed velocity of an unladen sparrow?

Approximately 27 kilofurlongs per fortnight.

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

On Fri, 23 Apr 2004 16:19:41 GMT, Thomas Matthews
< Thomas_MatthewsSpitsOnSpamBots@sbcglobal
.net> wrote:

>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.

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
removebalmerconsultingthis@att.net

Alan Balmer wrote:

> On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <horpner@yahoo.com> wrote:
>
> 
>
>
> 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.
> 
>
>
> What's the third question? :-)
>
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