Where is it better to include an header?

Question

Should I include my headers in the source file or in the .h?
Is header nesting (header include other headers) bad for any reason? If so, what is the reason?

Is it better to forward declare a struct in the header and include the needed header in the source file or to just include the needed header in the file where I need the struct?

I use to include them in the .c file but I wan't some clarification, thanks!

Answer 1

Should I include my headers in the source file or in the .h?

This is subjective. There's two different schools here:

• Header files should be included from the header since that documents all dependencies of your module to the user. Which module that is used by other modules is useful information when trying to link something, particularly when it was written by others.

• Header files should be included from the .c file as a way of encapsulation, because the caller need not know what the module does internally. For example the user shouldn't worry about internal headers which are not part of the public library API.

These two philosophies are not necessarily mutually exclusive. You combine these to include headers/dependencies that you want the user of the code to be aware of from the header, and to hide includes that the user need not be aware of in the .c file.

So it might also depend on what kind of code you are writing - is it an end application or some library to be used by other applications?

---

Is header nesting (header include other headers) bad for any reason?

It is normal practice, assuming that the headers were written properly. That means: using header guards (#ifndef HEADER_H #define HEADER_H etc) and not defining any variables inside the header.

Modules that depend on a certain inclusion order are badly written. Properly written modules include all the resources it needs (be it from the .h file or the .c file) so that it is autonomous.

If I include baker.h and want to use bread(), then there shouldn't exist some weird precondition that I must first include flour.h. It's not the caller's business to do that - whoever wrote baker.h failed to make it autonomous.

As mentioned in comments, circular dependencies are always a sign of incorrect design. You should never have a situation where a.h includes b.h and b.h directly/indirectly includes a.h. All relations between modules in a program is either an "a uses b" relation or an "a is a kind of b" relation (inheritance).

For example, the protocol handler uses the low-level driver, but it would be senseless for the low-level driver to include the protocol handler, because it shouldn't worry about the higher application layers.

Or in case of inheritance, dog.h and cat.h may include animal.h. But in case animal.h also includes dog.h then we have created a "tight coupling" between dog.h and cat.h and now the user can't use "cat" without also having access to the unrelated "dog" (if it even links in the first place). That's a senseless design.

Ultimately you will have one file like main.c which is the top layer of the whole application and that one either directly or indirectly includes every header part of the project.

---

Is it better to forward declare a struct in the header and include the needed header in the source file or to just include the needed header in the file where I need the struct?

That's a different topic. A struct forward declaration in the header means that nobody but the .c file containing the struct definition will have access to the internals of that struct. This is a design pattern often done on purpose and known as opaque type, to achieve private encapsulation in C.

Answer 2

• .c files reference external functions, object, types, defines, etc.
  Include the .h files that declare/define them.^*1
  Do not be overly concerned about including an extra unneeded <x.h> file.

• If file xxx.c has a paired xxx.h file, include that first for better debugging, otherwise order should not make a difference.

• .h files reference external functions, object, types, defines, etc.
  Include the .h files that declare/define them.^*1
  Avoid including any extra unneeded x.h file.
  .h files should begin/end with code guards, or equivalent, to well handle repeated inclusions.
  A .h file should be able to be compiled on its own. @Filippo.

---

^*1 Given the original file (a.c/a.h), if the included file b.h relies on another file: c.h, rely on b.h to include it rather than add an include to a.c/a.h. Yet a.c/a.h should include c.h if it directly needs that definition.