Loading...

C essentialsModular C

Header files & include guards

8 min lesson

Next
  • 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.
Keep in mind
  • 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!
math_utils.h
#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_H

Checks whether the guard name is not yet defined. If it is already defined, the whole header is skipped.

Define the guard

#define MATH_UTILS_H

Marks 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

#endif

Closes 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 guard

Use instead

#ifndef MATH_UTILS_H #define MATH_UTILS_H ... #endif

Without 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 .h

Use instead

int add(int a, int b); // declaration in .h

If 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.
Previous
Next