#include statement location: best practices

[jephthah]

so there's an argument about best practice for #include statements.

many people put all the relevant #include <header.h> statements at the top of the .c source code.

some people prefer to put the relevant #include statements within the .h header file that is associated with the .c source code

consider:

Example 1

"source.c"

#include <library1.h>
#include <library2.h>
#include <library3.h>
#include "another.h"
#include "etc.h"
#include "source.h"

int main(void)
{
    //etc...

"source.h"

#ifndef _SOURCE_H
#define _SOURCE_H

#define RELEVANT_MACRO_IN_SOURCE_C   
//etc...

#endif

Example 2

"source.c"

#include "source.h"

int main(void)
{
    //etc...

"source.h"

#ifndef _SOURCE_H
#define _SOURCE_H

#include <library1.h>
#include <library2.h>
#include <library3.h>
#include "another.h"
#include "etc.h"

#define RELEVANT_MACRO_IN_SOURCE_C  

//etc...

#endif

FTR, i'm in the camp for Example 2. It's my personal preference housekeeping sort of thing, but some people claim that including #includes within the header file is bad practice.

with the include guards, i'm not sure why that would be a problem, assuming you don't have circular references.

thanks

[gerard4143]

The only difference I can see is, if you use the second method you have to open and update the header.h file whenever you need a new libraries functionality..The first method, just add the include at the top of the file no updating a header file.

[L7Sqr]

My preference is to include header files where they are needed. If you need to functionality of stdio.h in your header (i.e you need to use FILE ) the include it otherwise it is just noise.

[jephthah]

The only difference I can see is, if you use the second method you have to open and update the header.h file whenever you need a new libraries functionality..The first method, just add the include at the top of the file no updating a header file.

i can't imagine why you would ever need a completely new library in your otherwise static code.... and even if you did, how would it be better to have to change the source code rather than the header file? in either case you will still have to recompile and redistribute a new version

My preference is to include header files where they are needed. If you need to functionality of stdio.h in your header (i.e you need to use FILE ) the include it otherwise it is just noise.

obviously. I only include library headers that are needed. "source.c" includes "source.h", which itself contains all the #defines, typedefs, #includes, etc. that "source.c" needs.

what i'm asking here is what is the "Best Practices" for including header files? is there a real reason why you should not put the #include statements in the header .H file? Or, at least, is there some reason why it's better to put your #includes in the source .C file?

thanks

[gerard4143]

Your original posting never mentioned anything about static source code.

[WaltP]

If source2.c doesn't need anything in library1.h, library2.h, another.h, etc.h, why include them? As L7Sqr said, it's just noise. The compiler is doing work for no gain.

[jephthah]

I'm sorry, I'm not explaining myself clearly. I'm not saying to use a single "catch all" header file for every single source file. each source file has it's own header file.

a second source such as the "source2.c" that Walt cites -- or "whatever.c" for that matter -- would not use the "source.h" file previously described.

"source2.c" will have its own corresponding "source2.h". "whatever.c" will have its own corresponding "whatever.h". and these individual header files will have only those #includes, #defines, etc. that their corresponding source files require.

as for static code, I mean it's not interpreted. you can't just change or add new a library on the fly and expect your code to just use it. if you change the name of the #included library, you must recompile your code to incorporate that library's interface whether the library is called from the source or the header.

[WaltP]

"source2.c" will have its own corresponding "source2.h". "whatever.c" will have its own corresponding "whatever.h". and these individual header files will have only those #includes, #defines, etc. that their corresponding source files require.

In my opinion, if nothing in the header is used elsewhere, the header is unnecessary. All can be defined in the C source.

That doesn't mean you can't create one for the purpose of uncluttering the source. But in general, if it's not used in another module, a header would just be another file requiring and complicating maintenance.

[Ancient Dragon]

If you ever used a Microsoft compiler you would know that they always produce stdafx.h, which is a catch-all for other includes. The most useful use of it is to compile c++ programs with pre-compiled headers. But this is a C forum and not C++ so precompiled headers is not relevant to the discussion.

I've used a combination of header files that include other header files which are common to all *.c files in the project. Header files which are not common are put directly into the *.c file that uses them.

[jephthah]

i totally agree that it is poor practice to include libraries for source code that is not used by that source code.

i also agree there is no value for creating extra header files just for the sake of sticking some includes in there. i have multiple header files to keep track of the large number of prototypes, constants, macros and conditional preprocessor directives. my current project has over 20 different .C source files, and at least 15 of them have their own header files.

Now I also like to put the include files in there while i'm at it. some have suggested that is bad practice, but they have not sufficiently explained why.

i guess the end result of my question is that, as long as you avoid unnecessary or redundant calls, it doesnt matter where you put your various includes, defines, etc.

[WaltP]

Now I also like to put the include files in there while i'm at it. some have suggested that is bad practice, but they have not sufficiently explained why.

I guess that would depend on what they are for and of putting them in a subdirectory would make the process cleaner. Personal preference IMO.

[Ancient Dragon]

20 years ago it would make a lot of difference where you put include files due to slooooow compilers and slooooow operating systems. Under MS-DOS 6.X I used to start a compile and go read a book or two. We tried to speed things up by including only the header files that were absolutely necessary.

Todays high-speed computers, operating systems, and compilers do not have that problem, except for very very large programs or groups of programs.