C Header Files – Best Practices for C Header File Order

Architectureccoding-style

I see that in many projects and examples that local includes are listed before external libs and before header files for built in compiler functionality.

Is there any advantage here that I am missing?

I have always used the following model:

1) built in header files
2) External lib header file
   A) External lib dependent on previous lib header file
3) custom project libs
4) local project header files

For example:

#include <stdio.h>
#include <stdlib.h>

#include <SDL2/SDL.h>
#include <SDL2/SDL_image.h>
#include <SDL2/SDL_ttf.h>

#include "DisplayInfo.h"

#include "projectModule.h"

Is this wrong or bad practice?

Best Answer

Is there any advantage here that I am missing?

Yes, there is. I, along with a large number of software projects, used to follow the practice outlined in the question. Many projects, including modern ones I work on, now take the opposite approach in a source file:

The header file that declares the functions being defined in the source file is the very first that is included.
Other header files from the same project are included next.
Header files from non-standard projects (e.g., eigen, boost, Qt) are included after local headers.
Finally, standard header files are included last.
Out of order inclusions need to be clearly documented with regard to why the header was not included in the above order.

Ideally, all header files should be self-contained, and inclusion order should not matter. In practice, people often write header files that are not self-contained, and sometimes inclusion order does matter. To combat the first problem, that the first included file is the header file that declares the functions that are being defined in a source file creates a nice test that a header file is indeed self-contained. Compilation errors that result from that very first included file means there's a bug in that header.

To combat the second problem (an out of order inclusion is necessary), that should be viewed as a code smell. If the code smell is in your own project code, the best thing to do is do fix it. Code smells are occasionally a stinky necessary. Suppose, for example, you are using what would otherwise be a great third party library were it not for the fact that its header files are not self-contained. You use the library because all alternatives are worse, but you document the out of order inclusions.

This latter problem is becoming rarer as projects adopt inside-out inclusion practices (local first, system last). That old-style inclusion order hurts software quality.

Related Solutions

C++ – How to Nicely Use Constant std::string in C++

Hardcoding such strings is generally considered to be bad practice.

Not sure I agree with that.

String literals are easy to read rather than the name of a string. If you want the same text for multiple locations then encapsulate the text into a function and call the single function to display the message.

If you want to centralize the text into a single file. Then what you are looking for is: strings as resources not manually moving all your string literals to string variables.

Checkout the following packages (normally used in localization but will work here).

* gettext

Basically what this package does is allow you to leave the 'English' version of the message in the code. But it will use the 'English' text as a key into a resource table to get the corrct version of the string for a particular local.

So code that looked like this:

printf ("and suddenly there's one line which is good..");

// Now looks like this:

printf (gettext ("and suddenly there's one line which is good.."));

You do not need to go through the hassel of extracting all your constant strings into another package.

See here for full details. http://www.gnu.org/software/gettext/

Personally I use the above in combination with boost format libraries for localization.

std::cout << boost::formt("The time is %1 in %2.") % time % country;

becomes:

std::cout << boost::formt(gettext("The time is %1 in %2.")) % time % country;

English Resource File:      "The time is %1 in %2."
Azerbaijani Resource File:  "Saat %2 saat %1 deyil."

C Programming – Including Local Headers First

If a header file such as file.h depends on other headers such as stdio.h, then file.h should #include those headers as necessary.

Each header file should keep track of its own dependencies, and use #include guards to prevent multiple translation if it winds up being included several times:

#ifndef FILE_H
#define FILE_H

#include <stdio.h>
...
void myfunc(FILE *);
...
#endif

This way the order of the includes simply doesn't matter, which makes maintenance much less crazy-making.

Best Answer

Related Solutions

C++ – How to Nicely Use Constant std::string in C++

C Programming – Including Local Headers First

Related Topic