Rob Pike's simple Include rule

Discussion in 'C Programming' started by Neil Cerutti, Apr 22, 2004.

  1. Neil Cerutti

    Neil Cerutti Guest

    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, Apr 22, 2004
    #1
    1. Advertising

  2. Neil Cerutti

    Sam Dennis Guest

    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"
     
    Sam Dennis, Apr 22, 2004
    #2
    1. Advertising

  3. Neil Cerutti

    Alan Balmer Guest

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


    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
     
    Alan Balmer, Apr 22, 2004
    #3
  4. E. Robert Tisdale, Apr 22, 2004
    #4
  5. "Neil Cerutti" <> wrote in message
    news:c6948r$9gmec$-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
     
    Stephen Sprunk, Apr 22, 2004
    #5
  6. Neil Cerutti

    Neil Cerutti Guest

    In article <>, Alan
    Balmer wrote:
    > On 22 Apr 2004 18:52:12 GMT, Neil Cerutti <> 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? :)


    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, Apr 23, 2004
    #6
  7. 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
     
    Thomas Matthews, Apr 23, 2004
    #7
  8. Neil Cerutti

    CBFalconer Guest

    Neil Cerutti wrote:
    > Alan Balmer wrote:
    >> Neil Cerutti <> 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? :)

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


    Approximately 27 kilofurlongs per fortnight.

    --
    Chuck F () ()
    Available for consulting/temporary embedded and systems.
    <http://cbfalconer.home.att.net> USE worldnet address!
     
    CBFalconer, Apr 23, 2004
    #8
  9. Neil Cerutti

    Alan Balmer Guest

    On Fri, 23 Apr 2004 16:19:41 GMT, Thomas Matthews
    <> 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
     
    Alan Balmer, Apr 23, 2004
    #9
  10. Alan Balmer wrote:

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

    >
    >
    > 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? :)
    >

    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
     
    Nick Landsberg, Apr 23, 2004
    #10
  11. Neil Cerutti

    Dan Pop Guest

    In <c6948r$9gmec$-berlin.de> Neil Cerutti <> writes:

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


    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.

    >2. How does a header state implicitly what it requires for
    >headers?


    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, Apr 23, 2004
    #11
  12. CBFalconer <> writes:
    > Neil Cerutti wrote:
    > > Alan Balmer wrote:
    > >> Neil Cerutti <> 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? :)

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

    >
    > Approximately 27 kilofurlongs per fortnight.


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

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

    --
    Keith Thompson (The_Other_Keith) <http://www.ghoti.net/~kst>
    San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
    Schroedinger does Shakespeare: "To be *and* not to be"
     
    Keith Thompson, Apr 23, 2004
    #12
  13. In article <c6blav$28k$>, (Dan Pop)
    wrote:

    > In <c6948r$9gmec$-berlin.de> Neil Cerutti
    > <> writes:
    >
    > >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?

    >
    > 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.
    >
    > >2. How does a header state implicitly what it requires for
    > >headers?

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


    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.
     
    Christian Bau, Apr 23, 2004
    #13
  14. Christian Bau wrote:

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


    This is equivalent to saying that header files should be

    1. self sufficient and
    2. idempotent.
     
    E. Robert Tisdale, Apr 23, 2004
    #14
  15. Neil Cerutti

    xarax Guest

    "Nick Landsberg" <> wrote in message
    news:jZbic.14249$...
    > Alan Balmer wrote:
    >
    > > On 22 Apr 2004 18:52:12 GMT, 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.
    > >>


    /snip/

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


    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).
     
    xarax, Apr 23, 2004
    #15
  16. Neil Cerutti

    CBFalconer Guest

    Keith Thompson wrote:
    > CBFalconer <> writes:
    > > Neil Cerutti wrote:
    > >

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

    >>
    >> Approximately 27 kilofurlongs per fortnight.

    >
    > Actually, it's about 60 to 66 kilofurlongs per fortnight
    > (10 to 11 meters/second).
    >
    > <http://www.style.org/unladenswallow/>


    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 () ()
    Available for consulting/temporary embedded and systems.
    <http://cbfalconer.home.att.net> USE worldnet address!
     
    CBFalconer, Apr 23, 2004
    #16
  17. In article <jZbic.14249$> writes:
    > 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.)


    I do not know from what time Pike's guideline comes, but I think it
    is an old guideline, and indeed made sense with old versions of make
    without additional tools.

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


    That is why already quite early the command 'makedepend' was created
    which would get all dependencies and add them to the makefile.
    --
    dik t. winter, cwi, kruislaan 413, 1098 sj amsterdam, nederland, +31205924131
    home: bovenover 215, 1025 jn amsterdam, nederland; http://www.cwi.nl/~dik/
     
    Dik T. Winter, Apr 24, 2004
    #17
  18. CBFalconer <> writes:
    > Keith Thompson wrote:
    > > CBFalconer <> writes:
    > > > Neil Cerutti wrote:
    > > >

    > ... snip ...
    > >>>
    > >>> 3. What is the average air-speed velocity of an unladen sparrow?
    > >>
    > >> Approximately 27 kilofurlongs per fortnight.

    > >
    > > Actually, it's about 60 to 66 kilofurlongs per fortnight
    > > (10 to 11 meters/second).
    > >
    > > <http://www.style.org/unladenswallow/>

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


    I see now that I didn't read your original question carefully enough.
    You asked about sparrows, not swallows. Since sparrows are much
    slower than swallows, you may have been pretty close. (27 kf/fn is
    about 10 mph or 4.5 meters/second, which seems plausible for a
    sparrow, though I don't have any actual figures.)

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


    Sorry, maximum acceleration of sparrows and swallows is off-topic.

    --
    Keith Thompson (The_Other_Keith) <http://www.ghoti.net/~kst>
    San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
    Schroedinger does Shakespeare: "To be *and* not to be"
     
    Keith Thompson, Apr 24, 2004
    #18
  19. xarax wrote:
    > "Nick Landsberg" <> wrote in message
    > news:jZbic.14249$...
    >
    >>Alan Balmer wrote:
    >>
    >>
    >>>On 22 Apr 2004 18:52:12 GMT, 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.
    >>>>

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

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


    <OT>
    "Most" does not include "all" by definition.

    (Not being sarcastic, just realistic.) All it takes
    is one developer who doesn't do it and the house of cards falls.

    I have personally rapped the knuckles of those
    who did not in the days when I was the "integrator".

    Actually, it's easier to change the makefile to
    have a dependency on both a.h and b.h rather than
    use the "touch" command.
    </OT>

    --
    "It is impossible to make anything foolproof
    because fools are so ingenious"
    - A. Bloch
     
    Nick Landsberg, Apr 24, 2004
    #19
  20. In article <>,
    "E. Robert Tisdale" <> wrote:

    > Christian Bau wrote:
    >
    > >
    > >
    > > 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.

    >
    > This is equivalent to saying that header files should be
    >
    > 1. self sufficient and
    > 2. idempotent.


    Bugger off, you idiot.
     
    Christian Bau, Apr 24, 2004
    #20
    1. Advertising

Want to reply to this thread or ask your own question?

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. nileppez
    Replies:
    1
    Views:
    390
    Tor Iver Wilhelmsen
    Aug 19, 2003
  2. Danny Anderson
    Replies:
    5
    Views:
    517
    Victor Bazarov
    Aug 15, 2003
  3. Replies:
    0
    Views:
    1,391
  4. Andreas Bogenberger
    Replies:
    3
    Views:
    960
    Andreas Bogenberger
    Feb 22, 2008
  5. Yahoo

    SRE (Simple Rule Engine)

    Yahoo, Jun 1, 2005, in forum: ASP .Net Web Controls
    Replies:
    3
    Views:
    238
    Yahoo
    Jun 30, 2005
Loading...

Share This Page