Header files & include guards
8 min lesson
- A header file is a .h file that declares functions, types and macros so other files can use them without copying code.
- Headers matter because they let you split a program into modules while keeping one shared description of what each module offers.
- Think of a header as a restaurant menu: it lists what is available without showing the kitchen's recipes.
- A declaration tells the compiler a function exists: int add(int a, int b);. The definition with the body lives in a .c file.
- An include guard is a set of preprocessor lines that prevent the same header from being included twice.
- The syntax for a guard is: #ifndef NAME_H, #define NAME_H, the contents, and #endif.
- The computer pastes the header contents at each #include; the guard ensures the body is pasted only once per translation unit.
- A realistic use: a math_utils.h that declares add and multiply, used by main.c and other files.
- A surprising detail: putting function definitions in a header included by many files causes multiple-definition errors at link time; headers should declare, not define.
- The example program is a small header with an include guard and a matching source file that uses it.
- Put declarations in headers and definitions in .c files.
- Always add an include guard to every header.
- Include only what you need in each file to keep compilation fast.
- Never define non-inline functions in a header.
- Modular C starts here. You are building real structure now!
#ifndef MATH_UTILS_H
#define MATH_UTILS_H
// Declarations only: no function bodies in the header
int add(int a, int b);
int multiply(int a, int b);
#endif // MATH_UTILS_H
// ---- In a separate file math_utils.c ----
// #include "math_utils.h"
// int add(int a, int b) { return a + b; }
// int multiply(int a, int b) { return a * b; }
// ---- In main.c ----
// #include <stdio.h>
// #include "math_utils.h"
// int main(void) {
// printf("%d\n", add(2, 3));
// return 0;
// }Breaking it down
Include guard start
#ifndef MATH_UTILS_HChecks whether the guard name is not yet defined. If it is already defined, the whole header is skipped.
Define the guard
#define MATH_UTILS_HMarks the header as seen. The next time the header is included, #ifndef fails and the contents are skipped.
Declarations
int add(int a, int b);Tells the compiler the signature of add so other files can call it. The body lives in a .c file.
Guard end
#endifCloses the conditional block. Every #ifndef must have a matching #endif.
A helpful analogy
A header file is like a restaurant menu. The menu lists the dishes (declarations) so customers know what is available, but the recipes (definitions) stay in the kitchen. The include guard is like a note that says 'this menu is already on the table', so the waiter does not bring a second copy.
Nesting rules
- 1.Every header needs a unique include guard, usually named after the file, like MATH_UTILS_H.
- 2.Headers should contain declarations, macros and type definitions, not function bodies.
- 3.Use angle brackets for system headers and double quotes for your own headers.
- 4.Keep each header focused on one module so dependencies stay clear.
Common mistakes
Forgetting the include guard
Avoid
// math_utils.h without guardUse instead
#ifndef MATH_UTILS_H
#define MATH_UTILS_H
...
#endifWithout a guard, including the header twice (directly and indirectly) causes duplicate declarations and compile errors.
Defining a function in a header
Avoid
int add(int a, int b) { return a + b; } // in .hUse instead
int add(int a, int b); // declaration in .hIf the header is included by several .c files, the linker sees multiple definitions of add and reports an error.
Using quotes for system headers
Avoid
#include "stdio.h"Use instead
#include <stdio.h>Angle brackets search system include paths. Quotes search the local directory first, which can pick up the wrong file.
Quick tips
- •Name the guard after the file path, like PROJECT_MATH_UTILS_H, to avoid clashes.
- •Include your own header in its .c file first to catch missing includes early.
- •Keep headers small; a huge header slows compilation for every file that includes it.
- •Try including math_utils.h twice in main.c to confirm the guard works.
- •Use #pragma once as a shorthand on compilers that support it, but prefer guards for portability.