⭐Understanding C Language Header Files and Macro Definitions: Grasping <span>#include</span> and <span>#define</span> and ‘Include Guards’

Author: IoT Smart Academy

Continuing from previous comprehensive projects: We have already used the <span>student.h / student.c / main.c</span> multi-file structure, and have also written

#ifndef STUDENT_H
#define STUDENT_H
...
#endif

However, many students actually just “copy and use” without truly understanding. This article will specifically clarify header files + macro definitions + conditional compilation in one go.

1. Why are there suddenly a bunch of things starting with “#”?

In our comprehensive project, you have already seen these usages:

#include <stdio.h>
#include "student.h"

#define MAX_STU 300

#ifndef STUDENT_H
#define STUDENT_H
/* ... */
#endif

These are not ordinary C statements, but rather preprocessor directives.

You can understand it this way:

Before a C program is actually compiled, it first goes through a “preprocessor” that performs text replacement + file concatenation. All <span>#</span> prefixed directives take effect “before compilation”.

Common preprocessor directives include:

• <span>#include</span>: “copy” the content of another file in
• <span>#define</span>: create a “replacement” macro definition (constants, simple formulas)
• <span>#if / #ifdef / #ifndef / #else / #endif</span>: conditional compilation, such as “compile only once” etc.

Understanding them, you will know:

• What exactly is a header file
• Why do we need <span>#ifndef STUDENT_H</span>
• <span>MAX_STU</span> is transformed into the number 300

2. <span>#include</span>: “embedding” a file

1. Basic Usage

#include <stdio.h>    // System header file (angle brackets)
#include "student.h"  // User-defined header file (double quotes)

Simply put:

<span>#include xxx</span> means “copy the entire content of xxx here”.

Difference between angle brackets <span>< ></span> and double quotes <span>" "</span>:

• <span>#include <stdio.h></span>: The compiler first looks in the system standard library path (e.g., C standard library, system header files).
• <span>#include "student.h"</span>: The compiler first looks in the current directory, and if not found, then looks in the system path.

Therefore, header files in your own project are generally written as:

#include "student.h"
#include "sensor.h"

2. What should be included in a header file?

In our previous <span>student.h</span>, we wrote:

typedef struct { ... } Student;
typedef struct { ... } StudentDB;

void initStudentDB(StudentDB *db);
void addStudents(StudentDB *db);
...

Principle: A header file is a “manual”:

• Contains “what this module looks like”: structures, macro definitions
• Contains “what this module can do”: function declarations

What should not be included:

• Generally, do not include function implementations (implementations are written in <span>.c</span>)
• Do not include definitions of global variables (you can include <span>extern</span> declarations)

In simple terms:

<span>.h</span> is the “interface declared to the outside”, while <span>.c</span> is “how it works inside”.

3. <span>#define</span>: Giving a “replacement” name to numbers/expressions

1. Constant Macros: Naming Numbers

The most common usage is this type:

#define MAX_STU 300
#define PI      3.1415926
#define OK      1
#define ERROR   0

Before compilation, the preprocessor does one thing:

It replaces all instances of <span>MAX_STU</span> in the code with <span>300</span>.

Note: This is simple “text replacement”, not a variable.

Advantages:

• Easy to modify: Changing <span>MAX_STU</span> once affects the entire project
• Better readability: Seeing <span>MAX_STU</span> immediately conveys meaning, much better than “300”

2. Expression Macros: Writing Small Formulas

For example, to calculate the area of a circle:

#define PI 3.1415926
#define AREA(r) (PI * (r) * (r))

double s = AREA(10);   // Expands to: 3.1415926 * (10) * (10)

⚠ A special reminder for students: Macros are “pure replacements”, so always use parentheses:

#define DOUBLE(x)  ( (x) + (x) )

int a = 3;
int b = DOUBLE(a + 1);  // Expands to: ( (a + 1) + (a + 1) )

If you write it as:

#define DOUBLE(x)  x + x

Then <span>DOUBLE(a + 1)</span> will become:

a + 1 + a + 1       // Still valid, but can easily lead to errors in more complex cases

Summarizing a sentence for students to memorize:

All parameters used in macros should be enclosed in parentheses.

4. What is “Include Guard” protecting against?

You often see this segment in <span>student.h</span>:

#ifndef STUDENT_H
#define STUDENT_H

// This is the main content of student.h

#endif

This is called Include Guard, used to prevent “the same header file from being compiled multiple times”.

1. What problems can arise?

Assuming these three lines are not present, you wrote:

// student.h
typedef struct { ... } Student;

Then two <span>.c</span> files do the following:

// a.c
#include "student.h"
#include "student.h"   // Included again (possibly indirectly)

// b.c
#include "student.h"

Finally, the compiler sees two instances in the same compilation unit:

typedef struct { ... } Student;
typedef struct { ... } Student;

This will cause an error:<span>redefinition of 'Student'</span><span> (redefinition).</span>

In real projects, it may not be you manually writing <span>#include</span> twice, but rather:

• <span>main.c</span> includes <span>"student.h"</span>
• <span>sensor.c</span> also includes <span>"student.h"</span>
• In some complex scenarios, header files may include each other, leading to duplication.

2. How do <span>#ifndef / #define / #endif</span> work?

Look at the logic of these three lines:

#ifndef STUDENT_H   // If “STUDENT_H has not been defined”
#define STUDENT_H   // Then define STUDENT_H now

// … The content in this area will only be retained once …

#endif              // End of condition

Explanation:

1. First <span>#include "student.h"</span>:

• <span>STUDENT_H</span> has not been defined → <span>#ifndef</span> condition is true → The compiler will see the entire header file content;
• <span>#define STUDENT_H</span> is executed, marking it as “defined” from now on.

Later, when <span>#include "student.h"</span> is encountered:

• <span>STUDENT_H</span> has already been defined → <span>#ifndef STUDENT_H</span> condition is false → The large chunk of content in between is skipped.

Thus, no matter how many <span>.c</span> files include <span>"student.h"</span>, the compiler will ultimately see only one definition.

Analogy:

At the entrance, someone asks: “Has STUDENT_H been in?”

• If not in → Let it in and mark: “Has been in”.
• If it comes again → “You have been in, go back.”

5. Conditional Compilation: Compile certain code only under “certain conditions” (basic understanding)

In larger projects, you often see these usages:

#define DEBUG   1

#if DEBUG
    printf("Debug info: x = %d\n", x);
#endif

This means:

• If the <span>DEBUG</span> macro is defined and its value is true (non-zero), then compile the <span>printf</span> line;
• Otherwise, this debugging code will be swallowed by the preprocessor as if it was never written.

You will also see:

#ifdef _WIN32
    // Only compile here under Windows
#endif

#ifdef __linux__
    // Only compile here under Linux
#endif

These are more commonly used for cross-platform code. For vocational students, just knowing this exists is sufficient.

6. Back to your comprehensive project: How to use header files and macros more规范?

Combining with the previous comprehensive project, let’s summarize a “standard version”.

1. Each module should have a <span>.h + .c</span>

• <span>student.h / student.c</span>: Related to students
• <span>sensor.h / sensor.c</span>: Related to sensors
• <span>util.h / util.c</span>: Related to utilities

Header file formats should be as uniform as possible:

#ifndef STUDENT_H
#define STUDENT_H

// 1. Necessary system header files
#include <stdio.h>

// 2. Macro definitions
#define MAX_STU 300

// 3. Structure definitions
typedef struct { ... } Student;
typedef struct { ... } StudentDB;

// 4. Function declarations
void initStudentDB(StudentDB *db);
...

#endif

2. How to include in <span>.c</span> files?

• <span>student.c</span> → <span>#include "student.h"</span>
• <span>sensor.c</span> → <span>#include "sensor.h"</span>
• <span>util.c</span> → <span>#include "util.h"</span>
• <span>main.c</span> → <span>#include "student.h"</span>, <span>#include "sensor.h"</span>, <span>#include "util.h"</span>

Note to still use double quotes <span>" "</span>.

3. Prefer using <span>#define</span> or <span>const</span>

For example:

#define MAX_STU     300
#define MAX_SENSOR  200

const float PI = 3.1415926f;   // Can also use const (safer)

Practical advice:

• For “capacity”, “array length”, “switch constants”, use <span>#define</span>.
• For “mathematical constants”, “physical constants”, etc., use <span>const variables</span>.

7. Hands-on Practice

Exercise 1: Add “Include Guards” to your module

Requirements:

1. Check your <span>student.h / sensor.h</span> to see if it already has <span>#ifndef / #define / #endif</span>;
2. If not, add complete header file protection;
3. Change macro names to all uppercase with underscores, for example: <span>STUDENT_H</span>, <span>SENSOR_H</span>.

Exercise 2: Use <span>#define</span> to replace “magic numbers”

In your code, check for these usages:

Student arr[300];
Sensor  arr[200];

if (score >= 60) { ... }

Replace these “bare numbers” with macros:

#define MAX_STU     300
#define MAX_SENSOR  200
#define PASS_SCORE  60

Then modify the related code to uniformly use macro constants.

Exercise 3: Try writing a simple conditional compilation

Add a “debug switch” in your project:

#define DEBUG 1   // Keep it on for now, can change to 0 to turn off

#if DEBUG
    printf("Current number of students: %d\n", db->count);
#endif

Requirements:

• Add this kind of debug output in key places like student entry and new device addition;
• Change <span>DEBUG</span> to 0, recompile and run, and observe whether these debug outputs disappear.

8. Summary Card

Quick Reference for C Language Header Files and Macro Definitions:

• <span>#include</span>: “Copy in the content of other files”; <span>< ></span> is for system, <span>" "</span> is for local.

• Header files <span>.h</span>: Only include “manuals”: structures, macros, function declarations.

• <span>#define</span>: Pure text replacement, commonly used for “constant macros” and “small expression macros” (remember to add parentheses).

• Include guard:

  #ifndef XXX_H
  #define XXX_H
  // ...
  #endif
  

  Prevents the same header file from being compiled multiple times.

• Conditional compilation:<span>#if / #ifdef / #ifndef / #endif</span>, commonly used to control “debug code” and “platform differences”.