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]

In article <cd**********@n ewstree.wise.ed t.ericsson.se>,
"John Smith" <so*****@micros oft.com> wrote:

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?

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]

"Christian Bau" <ch***********@ cbau.freeserve. co.uk> wrote in message
news:ch******** *************** **********@slb-newsm1.svr.pol. co.uk...

In article <cd**********@n ewstree.wise.ed t.ericsson.se>,
"John Smith" <so*****@micros oft.com> wrote:

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?

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.

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]

Hi John,

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?

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]

John Smith a couché sur son écran :

What does the group think of the practise of including one header file from
inside another?
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.
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.
Sounds like a design issue.
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.

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]

In <cd**********@n ewstree.wise.ed t.ericsson.se> "John Smith" <so*****@micros oft.com> writes:

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?

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: Da*****@ifh.de

[Dan Pop]

In <mn************ ***********@YOU RBRAnoos.fr> Emmanuel Delahaye <em***@YOURBRAn oos.fr> writes:

Heavy rules are raley useful. Better to act according to the situation.
I certainly hope that Emmanuel believes what he wrote above. (They're
called "strong rules", BTW.)
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.

^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^
Doesn't this rule render the first one superfluous? ;-)

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

[Arthur J. O'Dwyer]

On Wed, 21 Jul 2004, Christian Bau wrote:

"John Smith" <so*****@micros oft.com> wrote:

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

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

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]

On Wed, 21 Jul 2004 09:19:04 +0100, Christian Bau
<ch***********@ cbau.freeserve. co.uk> wrote:

In article <cd**********@n ewstree.wise.ed t.ericsson.se>,
"John Smith" <so*****@micros oft.com> wrote:

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

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

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

[Keith Thompson]

"Arthur J. O'Dwyer" <aj*@nospam.and rew.cmu.edu> writes:

On Wed, 21 Jul 2004, Christian Bau wrote:

"John Smith" <so*****@micros oft.com> wrote:

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

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.

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

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) ks***@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.