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

[E. Robert Tisdale]

John Smith wrote:

What does the group think
"Group think" is an intellectual disease.
of the practise of including one header file from inside another?
It is essential.
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?

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]

Da*****@cern.ch (Dan Pop) wrote in message news:<cd******* ***@sunnews.cer n.ch>...

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

No.

[pete]

kal wrote:

Da*****@cern.ch (Dan Pop) wrote in message news:<cd******* ***@sunnews.cer n.ch>...

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

No.

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]

In <a5************ **************@ posting.google. com> k_*****@yahoo.c om (kal) writes:

Da*****@cern.c h (Dan Pop) wrote in message news:<cd******* ***@sunnews.cer n.ch>...

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

No.

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

[John Smith]

"John Smith" <so*****@micros oft.com> wrote in message
news:cd******** **@newstree.wis e.edt.ericsson. se...

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

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?

[Arthur J. O'Dwyer]

On Thu, 22 Jul 2004, John Smith wrote:

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

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

What is this obsession with replying 'Don't forget the inclusion guard'???
It's old hat. My secnario has this in place.
Good. Many scenarios don't; or almost as bad, have incorrect header
guards, something like this picture. (A slightly interesting puzzle
is to count the number of mistakes in this header!)

#ifndef _MYHEADER_H
#define _MYHEADER_H

#ifdef __CPLUSPLUS__
extern 'C' {
#endif

#ifndef _STDIO_H
#include <stdio.h>
#endif

void foo(size_t bar);

#ifdef __CPLUSPLUS__
}
#endif
#endif

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.
Well, if you use a macro that's #defined in another module, that would
be a dependency, yes. I think we all assumed that was clear.
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!).
I would guess that very few people on this newsgroup have any experience
with your "overly sophisticated build system." Plain vanilla 'make' is
smart enough for many projects. And if a dependency on a /header file/
is causing any noticeable increase in compile time, I would say that your
build system has a design flaw.
So the question is: is it normal practise to create intermodule
dependancies for trivial reasons?

What counts as "trivial"? Most of my /programs/ are written for trivial
reasons (ranging from "because I want it" to "because I get paid to do it"
to "because I'm bored"). It sounds like you think this dependency is a
bad idea. Can you remove it without causing other bad side effects
(unmaintainabil ity, making the chief programmer jealous, breaking the
build tool)? If so, why don't you just go ahead and /do/ it?

Ask a vague question, get a vague answer.

-Arthur,
about seven

[Michael Mair]

Hi John,

What is this obsession with replying 'Don't forget the inclusion guard'???
It's old hat. My secnario has this in place.
Right. Not everyone told you this but you got answers to your question
as well.
The reason you get the "old hat" is that your question is vague enough
that we cannot be sure whether you are aware of the safe include
mechanism and the errors forgetting it can cause.

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.
Yes. You got answers to that. I gave one, people with more clue gave you
other answers.

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?

Try to ask clearer questions, please. "Trivial" is not clear in this
context. If the two settings I described are trivial, then: yes, if
one is not: no.

Hint: Filter out the static (that is: the inclusion guard stuff),
have a look at the remaining answers, try to come up with smart
questions based on these answers. Most of us certainly do not want to
frustrate you (having better things to do with their time).
Please try not to frustrate us in turn :-)
Cheers,
Michael

[John Smith]

"Michael Mair" <ma************ ********@ians.u ni-stuttgart.de> wrote in
message news:cd******** **@infosun2.rus .uni-stuttgart.de...

Hi John,

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

Right. Not everyone told you this but you got answers to your question
as well.
The reason you get the "old hat" is that your question is vague enough
that we cannot be sure whether you are aware of the safe include
mechanism and the errors forgetting it can cause.

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.

Yes. You got answers to that. I gave one, people with more clue gave you
other answers.

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?

Try to ask clearer questions, please. "Trivial" is not clear in this
context. If the two settings I described are trivial, then: yes, if
one is not: no.

Hint: Filter out the static (that is: the inclusion guard stuff),
have a look at the remaining answers, try to come up with smart
questions based on these answers. Most of us certainly do not want to
frustrate you (having better things to do with their time).
Please try not to frustrate us in turn :-)
Cheers,
Michael

Sorry if I have frustrated you all, it certainly wasn't my intention.

Thanks for all the replies. I'll figure something out of it all, I'm sure.

JS

[Jack Klein]

On Thu, 22 Jul 2004 14:20:19 +0100, "John Smith"
<so*****@micros oft.com> wrote in comp.lang.c:

"John Smith" <so*****@micros oft.com> wrote in message
news:cd******** **@newstree.wis e.edt.ericsson. se...

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

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?

In my opinion, a source file containing two single lines must compile
without diagnostics, or with only a diagnostic concerning the failure
of the translation unit to contain any external declarations:

#include "required_proje ct_header.h"
#include "header_in_ques tion.h"

....where "required_proje ct_header.h" is just that, required to be the
first header included in every C source file in the project. It in
turn includes at least <stdint.h> and <stddef.h>, plus generally some
project-specific headers with universally used typedef's and macros.

In setting up the rules for our latest large C embedded project, I
tried to eliminate some of the more obvious disadvantages of earlier
project structures. The biggest of these was "header dependency
hell".

In earlier projects, functions and data types that provided interfaces
between various modules of the program were all placed in a single
header for each module, named xxx_api.h for module xxx.

The problem is that xxx_api.h almost always needed to include some
type defined by a different module in some structure of its own, or
accept or return one (or a pointer to one) in a function call.

So xxx_api.h required the inclusion of yyy_api.h, which in turn needed
something from zzz_api.h, and in the end way too many files ended up
including most or all of the API headers.

The obvious solution, which has reduced these dependencies greatly, is
to require two headers for things exported by each module:

xxx_api_types.h
xxx_api_calls.h

The latter, of course, must include the former. A few simple rules:

1. C source files may only include *_calls.h files, and never any
*_types.h, other than that belonging to its own module.

2. *.api_calls.h files must include their own api_types.h file, and
may include other *api_types.h files, but may not include any other
api_calls.h files.

This has cut the header coupling down significantly.

If you are working with legacy code, and can't completely reorganize
the code base, consider moving the one dependency to a header file of
its own:

some_header_nam e.h:

#ifndef THIS_IS_DEFINED _IN_HEADER2
#define THIS_IS_DEFINED _IN_HEADER2 5
#endif

Include this header in the big include file in place of the
definition, and include it in other places that only needed this
symbol from the big include file.

This is the sort of thing that is a good candidate for inclusion in
"required_proje ct_header.h".

--
Jack Klein
Home: http://JK-Technology.Com
FAQs for
comp.lang.c http://www.eskimo.com/~scs/C-faq/top.html
comp.lang.c++ http://www.parashift.com/c++-faq-lite/
alt.comp.lang.l earn.c-c++
http://www.contrib.andrew.cmu.edu/~a...FAQ-acllc.html