ethic on Includes

[Jim]

Hi:

Do we have some common style for includes when working on a project
with lots of c and h files. Wat I mean is do we have a rule in C when
a file includes several files and those file in turn can call back it.
So do we keep the includes in the source file or in its header file
and just call the header from the c file. Are there any more rules
when we go for includes. Thanx to yu all who bother to share....

su

 

[Thomas Matthews]

Hi:

Do we have some common style for includes when working on a project
with lots of c and h files. Wat I mean is do we have a rule in C when
a file includes several files and those file in turn can call back it.
So do we keep the includes in the source file or in its header file
and just call the header from the c file. Are there any more rules
when we go for includes. Thanx to yu all who bother to share....

su

Officially, there are no rules for h files. The h files are not
necessary or required by the C language standard.

The common convention is to place declarations into header files.
The header files should have "include guards" to protect the
file from being parsed more than once by the compiler. An
example of an include guard:
#ifndef MY_HEADER_H
#define MY_HEADER_H
/* declarations */
#endif /* MY_HEADER_H */

Cyclic definitions should be minimized. Some techniques for
reducing cyclic definitions include "Refactoring" and forward
declarations. Search the web for "Refactoring".

--
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
http://www.sgi.com/tech/stl -- Standard Template Library

 

[Kevin Easton]

Officially, there are no rules for h files. The h files are not
necessary or required by the C language standard.

The common convention is to place declarations into header files.
The header files should have "include guards" to protect the
file from being parsed more than once by the compiler. An
example of an include guard:
#ifndef MY_HEADER_H
#define MY_HEADER_H
/* declarations */
#endif /* MY_HEADER_H */

It is better to adopt the style:

#ifndef H_MY_HEADER
....

because macros starting with E followed by another uppercase letter are
reserved (so using the other style, you'll have a problem for any header
file name starting with `e').

- Kevin.

 

[Matt Gregory]

Hi:

Do we have some common style for includes when working on a project
with lots of c and h files. Wat I mean is do we have a rule in C when
a file includes several files and those file in turn can call back it.
So do we keep the includes in the source file or in its header file
and just call the header from the c file. Are there any more rules
when we go for includes. Thanx to yu all who bother to share....

Having a lot of includes can increase compile time. It's a good idea
to minimize the number of header files that are included in other
header files, or not have any at all. Let's say you have a.h, b.h,
and b.c, and both b.h and b.c are dependent on a.h so both files
include a.h. Everytime you compile b.c, a.h is going to be opened
and parsed twice. If you add another header to b.c that includes a.h,
it's going to be parsed three times. If that header is also dependent
on b.h, then a.h is going to be parsed four times. It only needs to be
read once, so it's a just waste of time to include it all those times.
You can decide not include any headers in other headers. This means
you have to include the headers in the right order in your source files.
a.h would have to be included before b.h in every source file that
needs b.h. So that can be a real pain. You can get around that by
just making one header file with all the headers for the entire project
included in it and just include that in every source file. But then
every file you compile has to read every single header file every
time. If your compiler supports precompiled headers then it will
take of all that in one shot and you don't have to worry about it.
If you don't have precompiled headers and you don't want to include
every file every single time and you don't want to manually arrange
all of the headers for every file you can use external include
guards instead of the usual internal ones. This way, if the file
has already been included, it won't have to be opened at all. The
problem with this is that every time you include a file in a header
you have to wrap it in external guards:

#ifndef A_H
#include "a.h"
#endif
#ifndef B_H
#include "b.h"
#endif

If the code is well organized and modular then you won't really
have to worry about any of this. You just want to avoid including
files dozens or hundreds of times, which can happen if you have a
lot of includes in headers.

In short, the only rule with header files is that you don't want
them to increase compile time unnecessarily.

Matt Gregory

 

[Malcolm]

Do we have some common style for includes when working on a
project with lots of c and h files. Wat I mean is do we have a rule in C
when a file includes several files and those file in turn can call back it.
So do we keep the includes in the source file or in its header file
and just call the header from the c file. Are there any more rules
when we go for includes. Thanx to yu all who bother to share....

A structured program should be like a pyramid, with main() and the top and
sub functions getting steadily lower level and more general.
A multiple file program should also have files arranged like a pyramid. If
functions in foo.c call bar.c, bar.c shouldn't call foo.c.
The big debate is whether include files should #include files they are
dependent on. If bar.h defines struct BAR, and foo.h includes a function
that takes a BAR *, then there's a case for making foo.h #include bar.h. The
case against is that the dependency is then obscured.

Another problem is that a small number of functions do need to be mutually
recursive, and occasionally it makes sense to include logically related
functions in the same file, even though this means that the file contains
both caller and callee. In these cases you need to take a hard look at the
code and ask whether it really needs to be organised like that. If it does,
then break the rules.

 

[Derk Gwen]

# Do we have some common style for includes when working on a project
# with lots of c and h files. Wat I mean is do we have a rule in C when
# a file includes several files and those file in turn can call back it.
# So do we keep the includes in the source file or in its header file
# and just call the header from the c file. Are there any more rules
# when we go for includes. Thanx to yu all who bother to share....

I use header files to declare the interface, and source files for the implementation.
The interface would be the bare but complete minimum necessary to exploit the
interface. I include all header files necessary to define types and other objects
necessary to complete the interface.

The source file would include any interfaces it uses. These interfaces are internal
to the implementation and would not be exposed to the interface.

If you include guards in each header
#ifndef some_unique_tag
#define some_unique_tag
...
header file contents
...
#endif
then including the same header multiple times will not cause problems.

Separating interface and implementation makes it simpler to separate concerns.
Also if you build makefile dependencies from the #include, this will help
minimise recompiles if you change the implementation but not the interface.

 

[Jim]

Thanks to u all.. for ur feedback... as for the Refactoring, i really
didnt find much of material for c on the net...

 

[John Bode]

Hi:

Do we have some common style for includes when working on a project
with lots of c and h files. Wat I mean is do we have a rule in C when
a file includes several files and those file in turn can call back it.
So do we keep the includes in the source file or in its header file
and just call the header from the c file. Are there any more rules
when we go for includes. Thanx to yu all who bother to share....

su

You will want to avoid circular references wherever possible. They
may be unavoidable in some situations, but I can't think of an example
off the top of my head. If you have a situation where foo.h includes
bar.h and bar.h includes foo.h, you may want to rethink your design.
If nothing else, create a single foobar.h file and include it in both
foo.c and bar.c (and in any file that uses the functions defined in
foo.c and bar.c).

Personally, I find it best to let header files include whatever files
they need; that way you don't have to worry about the order of
includes in the source file (the header file is said to be
*indempotent*). Since this allows a situation where header files may
be included more than once per translation unit, you'll need to put
guard macros in the header file so that its contents are only parsed
once per translation unit:

#ifndef MY_HEADER_H
#define MY_HEADER_H

/* macros, typedefs, extern var declarations, function prototypes */

#endif /* MY_HEADER_H */

The first time the header file is parsed, MY_HEADER_H hasn't been
#defined, so the contents of the file are parsed. Each subsequent
time the header is parsed in that same translation unit, the
MY_HEADER_H macro will be defined, so the file contents will be
ignored.

 

[Kevin Easton]

Personally, I find it best to let header files include whatever files
they need; that way you don't have to worry about the order of
includes in the source file (the header file is said to be
*indempotent*). Since this allows a situation where header files may
be included more than once per translation unit, you'll need to put
guard macros in the header file so that its contents are only parsed
once per translation unit:

#ifndef MY_HEADER_H
#define MY_HEADER_H

I'll just point out, again, that it's probably better to adopt the
convention:

#ifndef H_MY_HEADER
#define H_MY_HEADER

instead, because macros starting with E followed by another capital
letter are reserved, so you wouldn't be able to have a header file
starting with e, follow the former convention and still have a legal C
program.

- Kevin.