Header files included in header files

[John Smith]

Hi all

What does the group think of the practise of including one header file from
inside another?

I have some legacy code where this has been done, and it creates a
dependency on a module (collection of files) which are not required, except
for one header file's contents.

I'd say 'No, header files should be included in the C source, not in another
header', but I've always come across strong arguments for the latter.

What do you think, and what is accepted practise?

Thanks
JS

[Christian Bau]

Re: Header files included in header files

In article <cdl6fm$lmj$1@n ewstree.wise.ed t.ericsson.se>,
"John Smith" <soneone@micros oft.com> wrote:
[color=blue]
> Hi all
>
> What does the group think of the practise of including one header file from
> inside another?
>
> I have some legacy code where this has been done, and it creates a
> dependency on a module (collection of files) which are not required, except
> for one header file's contents.
>
> I'd say 'No, header files should be included in the C source, not in another
> header', but I've always come across strong arguments for the latter.
>
> What do you think, and what is accepted practise?[/color]

If you write a header file "header.h", then it must be written in such a
way that the single line source file

#include "header.h"

compiles without errors. That means header.h needs to include everything
that is necessary to make this work, but not more.

Note that a function can have arguments or return values of type "struct
xxx *" without having the declaration of struct xxx around; this feature
of C often makes it unnecessary to include header files within header
files.

[John Smith]

Re: Header files included in header files


"Christian Bau" <christian.bau@ cbau.freeserve. co.uk> wrote in message
news:christian. bau-AF9E24.09190421 072004@slb-newsm1.svr.pol. co.uk...[color=blue]
> In article <cdl6fm$lmj$1@n ewstree.wise.ed t.ericsson.se>,
> "John Smith" <soneone@micros oft.com> wrote:
>[color=green]
> > Hi all
> >
> > What does the group think of the practise of including one header file[/color][/color]
from[color=blue][color=green]
> > inside another?
> >
> > I have some legacy code where this has been done, and it creates a
> > dependency on a module (collection of files) which are not required,[/color][/color]
except[color=blue][color=green]
> > for one header file's contents.
> >
> > I'd say 'No, header files should be included in the C source, not in[/color][/color]
another[color=blue][color=green]
> > header', but I've always come across strong arguments for the latter.
> >
> > What do you think, and what is accepted practise?[/color]
>
> If you write a header file "header.h", then it must be written in such a
> way that the single line source file
>
> #include "header.h"
>
> compiles without errors. That means header.h needs to include everything
> that is necessary to make this work, but not more.
>
> Note that a function can have arguments or return values of type "struct
> xxx *" without having the declaration of struct xxx around; this feature
> of C often makes it unnecessary to include header files within header
> files.[/color]

Thanks Christian

You have a good point about it having to compile. This particular header
problem has, in the first header, something like
typedef struct
{ int array[THIS_IS_DEFINED _IN_HEADER2]; } astruct;

and of course in the other header
#define THIS_IS_DEFINED _IN_HEADER2 5

This turns out to be the only dependant thing!
Normal practise, or poor coding?

Thanks
JS

[Michael Mair]

Re: Header files included in header files

Hi John,

[color=blue]
> You have a good point about it having to compile. This particular header
> problem has, in the first header, something like
> typedef struct
> { int array[THIS_IS_DEFINED _IN_HEADER2]; } astruct;
>
> and of course in the other header
> #define THIS_IS_DEFINED _IN_HEADER2 5
>
> This turns out to be the only dependant thing!
> Normal practise, or poor coding?[/color]

It depends. I am working with a huge code where you have hundreds
of header files. Many of the THIS_IS_DEFINED _IN_HEADER2 type
symbolic constants make sense insofar as you then can assume
that all arrays (in your example) serving a certain purpose
are of the same size -- the advantages are clear, I think.

On the other hand, if this symbolic constant does not have
a "deeper" meaning for the purpose of your array but only has
per chance the value 5 which you also have as the array size,
then it is poor coding.

If you are sure about the implications, you can also use a
construct like

#ifndef DONTWANNAINCLUD EIT
#include "header2.h"
#endif

#ifdef THIS_IS_DEFINED _IN_HEADER2
#define MY_ARRAY_SIZE THIS_IS_DEFINED _IN_HEADER2
#else
#define MY_ARRAY_SIZE 5
#endif

typedef struct {
int array[MY_ARRAY_SIZE];
} astruct;


Cheers,
Michael

[Emmanuel Delahaye]

Re: Header files included in header files

John Smith a couché sur son écran :[color=blue]
> What does the group think of the practise of including one header file from
> inside another?[/color]

This group is made of individuals fitted with free will (well, I guess)
and free speech (this, I know!). It may have some consensus on certain
points, but don't expect some 'unique way of thinking' from this group.
It's not a sectarian group. It's an open and free community. Expression
is individual.
[color=blue]
> I have some legacy code where this has been done, and it creates a
> dependency on a module (collection of files) which are not required, except
> for one header file's contents.[/color]

Sounds like a design issue.
[color=blue]
> I'd say 'No, header files should be included in the C source, not in another
> header', but I've always come across strong arguments for the latter.[/color]

Heavy rules are raley useful. Better to act according to the situation.

That said, here are some basics (call them rules if you want):

- A header should be guarded against multiple inclusions.
- A header should hold definitions of macros, types and structures [1]
and declarations of functions (in prototyped form) and objects.
- A header sould be included when needed. Not less, not more.

------------------
[1] and the definitions of inline functions in C99 or more.


And some more general recommendations :

- The code should be organized into individual functionnal blocks with
a clear public interface.
- The code should be unit testable.
- The public interface is defined in a header file that belongs to the
functionnal block.

This is an important design guideline that helps to make solid,
efficient and reusable code.

--


Emmanuel

[Dan Pop]

Re: Header files included in header files

In <cdl93n$mo0$1@n ewstree.wise.ed t.ericsson.se> "John Smith" <soneone@micros oft.com> writes:

[color=blue]
>You have a good point about it having to compile. This particular header
>problem has, in the first header, something like
>typedef struct
>{ int array[THIS_IS_DEFINED _IN_HEADER2]; } astruct;
>
>and of course in the other header
>#define THIS_IS_DEFINED _IN_HEADER2 5
>
>This turns out to be the only dependant thing!
>Normal practise, or poor coding?[/color]

It entirely depends on the application design. It is common practice
to have all the user-serviceable parts defined together in a single
header and all the other headers needing macros defined in that header
will have to include it. Ditto for special typedef's required by the
application.

IMHO, in a complex application with a well structured set of headers,
higher level headers will have to include lower level headers.

Of curse, I cannot make any comments WRT the design of your application.

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

[Dan Pop]

Re: Header files included in header files

In <mn.ab3a7d47eda 50960.15512@YOU RBRAnoos.fr> Emmanuel Delahaye <emdel@YOURBRAn oos.fr> writes:
[color=blue]
>Heavy rules are raley useful. Better to act according to the situation.[/color]

I certainly hope that Emmanuel believes what he wrote above. (They're
called "strong rules", BTW.)
[color=blue]
>That said, here are some basics (call them rules if you want):
>
>- A header should be guarded against multiple inclusions.
>- A header should hold definitions of macros, types and structures [1]
>and declarations of functions (in prototyped form) and objects.
>- A header sould be included when needed. Not less, not more.[/color]
^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Doesn't this rule render the first one superfluous? ;-)

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

[Arthur J. O'Dwyer]

Re: Header files included in header files


On Wed, 21 Jul 2004, Christian Bau wrote:[color=blue]
>
> "John Smith" <soneone@micros oft.com> wrote:[color=green]
> >
> > What does the group think of the practise of including one header
> > file from inside another?[/color][/color]
[color=blue]
> If you write a header file "header.h", then it must be written in such a
> way that the single line source file
>
> #include "header.h"
>
> compiles without errors. That means header.h needs to include everything
> that is necessary to make this work, but not more.[/color]

(Furthermore, it must be written in such a way that the /two-line/
source file

#include "header.h"
#include "header.h"

compiles without errors. That means header.h needs to include header
guards in the proper places.)
[color=blue]
> Note that a function can have arguments or return values of type "struct
> xxx *" without having the declaration of struct xxx around; this feature
> of C often makes it unnecessary to include header files within header
> files.[/color]

I wouldn't consider that good practice, though. If "header.h"
uses anything declared in "foo.h", then "header.h" ought to #include
"foo.h" on general principles, so that the maintainer can see the
dependency --- even if the compiler might not care. After all, you
certainly wouldn't want

==foo.h==

struct Foo {
int i;
};

==header.h==

struct Foo *hello(void);

==bar.h==

struct Foo {
int i[1024];
};

==myprog.c==

#include "bar.h"
#include "header.h"

when the implementation of 'hello()' was expecting to return a
pointer to the type defined in "foo.h"! Better to include all
dependencies, and shake out the bugs early.

-Arthur

[Alan Balmer]

Re: Header files included in header files

On Wed, 21 Jul 2004 09:19:04 +0100, Christian Bau
<christian.bau@ cbau.freeserve. co.uk> wrote:
[color=blue]
>In article <cdl6fm$lmj$1@n ewstree.wise.ed t.ericsson.se>,
> "John Smith" <soneone@micros oft.com> wrote:
>[color=green]
>> Hi all
>>
>> What does the group think of the practise of including one header file from
>> inside another?
>>
>> I have some legacy code where this has been done, and it creates a
>> dependency on a module (collection of files) which are not required, except
>> for one header file's contents.
>>
>> I'd say 'No, header files should be included in the C source, not in another
>> header', but I've always come across strong arguments for the latter.
>>
>> What do you think, and what is accepted practise?[/color]
>
>If you write a header file "header.h", then it must be written in such a
>way that the single line source file
>
> #include "header.h"[/color]

Agreed.[color=blue]
>
>compiles without errors. That means header.h needs to include everything
>that is necessary to make this work, but not more.
>
>Note that a function can have arguments or return values of type "struct
>xxx *" without having the declaration of struct xxx around; this feature
>of C often makes it unnecessary to include header files within header
>files.[/color]

Unnecessary, perhaps, but highly recommended nonetheless. There's no
good reason not to include the headers, and they should be there for
the benefit of the reader and so that the compiler can check the usage
of the function.

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

[Keith Thompson]

Re: Header files included in header files

"Arthur J. O'Dwyer" <ajo@nospam.and rew.cmu.edu> writes:[color=blue]
> On Wed, 21 Jul 2004, Christian Bau wrote:[color=green]
> > "John Smith" <soneone@micros oft.com> wrote:[color=darkred]
> > >
> > > What does the group think of the practise of including one header
> > > file from inside another?[/color][/color]
>[color=green]
> > If you write a header file "header.h", then it must be written in such a
> > way that the single line source file
> >
> > #include "header.h"
> >
> > compiles without errors. That means header.h needs to include everything
> > that is necessary to make this work, but not more.[/color]
>
> (Furthermore, it must be written in such a way that the /two-line/
> source file
>
> #include "header.h"
> #include "header.h"
>
> compiles without errors. That means header.h needs to include header
> guards in the proper places.)[/color]

For certain values of "must". The #include directive just (in effect)
dumps the contents of the named header or file into your source at the
specified place. The language imposes few requirements on the content
of the header or the manner in which it's included, as long as the
final result is legal C. If "header.c" contains the line

i++;

then obviously the placement and number of any #include directives
will be significant, and the compiler is unlikely to complain.

But of course that kind of thing is horrendously bad style and is
shunned by all right-thinking programmers.

Which is a long-winded way of saying that I agree entirely, except
that I would have written "should" rather than "must". The meta-point
is that it's a matter of style (which of course doesn't make it
unimportant).

--
Keith Thompson (The_Other_Keit h) kst-u@mib.org <http://www.ghoti.net/~kst>
San Diego Supercomputer Center <*> <http://users.sdsc.edu/~kst>
We must do something. This is something. Therefore, we must do this.

[E. Robert Tisdale]

Re: Header files included in header files

John Smith wrote:
[color=blue]
> What does the group think[/color]

"Group think" is an intellectual disease.
[color=blue]
> of the practise of including one header file from inside another?[/color]

It is essential.
[color=blue]
> I have some legacy code where this has been done,
> and it creates a dependency on a module (collection of files)
> which are not required, except for one header file's contents.
>
> I'd say 'No,
> header files should be included in the C source, not in another header',
> but I've always come across strong arguments for the latter.
>
> What do you think, and what is accepted practice?[/color]

Header files are files include'd by the C preprocessor
at the *head* of a C source file or another header file.
Files included elsewhere in the body of a source file
are not technically header files.

Header files are usually used to introduce *module interfaces*
into source programs. Such header files should be both

1. self-sufficient and
2. idempotent.

Self-sufficient means that the header file should include
all of the header files that it needs to compile properly.
Idempotent means that the content is protected by so-called
*guard macros"

#ifndef GUARD_FILE_H
#define GUARD_FILE_H 1
// contents
#endif//GUARD_FILE_H

that prevent the C preprocessor
from including the contents more than once.

Remember that an *interface* has no substance itself.
It contains function declarations, macro and type definitions
but nothing that would compel the compiler to emit code by itself.
Header files that effect module interfaces should *not* include
[global] function definitions!
This means that including unused interfaces should be *harmless* --
*no* dependencies should be created.

[kal]

Re: Header files included in header files

Dan.Pop@cern.ch (Dan Pop) wrote in message news:<cdlt9g$is i$2@sunnews.cer n.ch>...
[color=blue][color=green]
> >That said, here are some basics (call them rules if you want):
> >
> >- A header should be guarded against multiple inclusions.
> >- A header should hold definitions of macros, types and structures [1]
> >and declarations of functions (in prototyped form) and objects.
> >- A header sould be included when needed. Not less, not more.[/color]
> ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
> Doesn't this rule render the first one superfluous? ;-)[/color]

No.

[pete]

Re: Header files included in header files

kal wrote:[color=blue]
>
> Dan.Pop@cern.ch (Dan Pop) wrote in message news:<cdlt9g$is i$2@sunnews.cer n.ch>...
>[color=green][color=darkred]
> > >That said, here are some basics (call them rules if you want):
> > >
> > >- A header should be guarded against multiple inclusions.
> > >- A header should hold definitions of macros, types and structures [1]
> > >and declarations of functions (in prototyped form) and objects.
> > >- A header sould be included when needed. Not less, not more.[/color]
> > ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
> > Doesn't this rule render the first one superfluous? ;-)[/color]
>
> No.[/color]

If the main file #includes header file a.h,
which #includes header file b.h, which #includes header file c.h,
which has a FILE type parameter in a function prototype,
and which also #includes stdio.h, then I may be inclined,
when using a function like printf in the main file,
to also #include stdio.h in the main file,
even though it isn't needed there.

The reason being because I may want to be able to change
a.c and a.h, without changing the #includes in the main file.

It would depend on whether or not the features in a.c, a.h, b.c, b.h
and c.c, which required the inclusion of stdio.h,
were fundamental to the main file.

--
pete

[Dan Pop]

Re: Header files included in header files

In <a5da4cc1.04072 12111.1b8b477b@ posting.google. com> k_amir7@yahoo.c om (kal) writes:
[color=blue]
>Dan.Pop@cern.c h (Dan Pop) wrote in message news:<cdlt9g$is i$2@sunnews.cer n.ch>...
>[color=green][color=darkred]
>> >That said, here are some basics (call them rules if you want):
>> >
>> >- A header should be guarded against multiple inclusions.
>> >- A header should hold definitions of macros, types and structures [1]
>> >and declarations of functions (in prototyped form) and objects.
>> >- A header sould be included when needed. Not less, not more.[/color]
>> ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
>> Doesn't this rule render the first one superfluous? ;-)[/color]
>
>No.[/color]

Why? With few exceptions, no header *needs* to be included twice. And
these exceptions, obviously, don't have guards against multiple inclusion.

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

[John Smith]

Re: Header files included in header files


"John Smith" <soneone@micros oft.com> wrote in message
news:cdl6fm$lmj $1@newstree.wis e.edt.ericsson. se...[color=blue]
> Hi all
>
> What does the group think of the practise of including one header file[/color]
from[color=blue]
> inside another?
>
> I have some legacy code where this has been done, and it creates a
> dependency on a module (collection of files) which are not required,[/color]
except[color=blue]
> for one header file's contents.
>
> I'd say 'No, header files should be included in the C source, not in[/color]
another[color=blue]
> header', but I've always come across strong arguments for the latter.
>
> What do you think, and what is accepted practise?
>
> Thanks
> JS
>
>[/color]

What is this obsession with replying 'Don't forget the inclusion guard'???
It's old hat. My secnario has this in place.

My problem is one module is creating a dependancy on another module only
because the first module wants to use one single #define in the second
module.

The application is a large one, backed up by an overly sophisticated build
system, which would mean if I want to pick up module 2, I pick up all of it:
it all gets compiled. (And yes, I know: it won't get linked in!).

So the question is: is it normal practise to create intermodule dependancies
for trivial reasons?